Doc: translate newest animation doc to en #2553
Conversation
|
Caution Review failedThe pull request is closed. WalkthroughThis pull request updates and expands the animation documentation. Terminology, component names, and method signatures have been standardized (e.g., from “Animation Control Component” to “Animator Component” and “Animation Clip” to “AnimationClip”). Additionally, several new example guides have been added, covering topics like blending, input-controlled animations, cross-fading, material animation, sprite sheet, text animation, and more. Chinese documentation has also been updated for clarity and consistency. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant InputHandler
participant AnimatorController
participant Animator
User->>InputHandler: Press key (e.g. "W" / "Shift")
InputHandler->>AnimatorController: Update "speed" parameter
AnimatorController->>Animator: Trigger state transition (idle → walk/run)
sequenceDiagram
participant Animator
participant AnimatorController
participant AnimationState
Animator->>AnimatorController: Call animator.play("State Name", layerIndex, normalizedTimeOffset)
AnimatorController->>AnimationState: Initiate crossFade transition
Possibly related PRs
Suggested reviewers
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (16)
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
github-actions
bot
added
the
documentation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2553 +/- ##
==========================================
+ Coverage 68.59% 68.92% +0.32%
==========================================
Files 961 961
Lines 100219 100266 +47
Branches 8598 8678 +80
==========================================
+ Hits 68749 69109 +360
+ Misses 31210 30897 -313
Partials 260 260
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (15)
docs/en/animation/overview.mdx (1)
30-32: Consider adding more context about AnimationClips.The explanation could benefit from a brief example or use case to help readers better understand the concept.
The Galacean animation system is based on the concept of animation clips, which contain information about how certain objects should change their position, rotation, or other properties over time. Each AnimationClip can be considered a single linear recording. + +For example, an AnimationClip might contain: +- A walking animation that changes character position and rotation +- A color transition that modifies material properties +- A scaling effect that adjusts object dimensionsdocs/en/animation/examples/blending.mdx (2)
40-40: Improve readability of the instruction.The sentence contains multiple references and could be split for better clarity.
-Add an `Animation State` (if you don't know how to add it, please refer to: [Play Animation in Model](/docs/animation/examples/playAnimation/)), bind the **"shakeHead"** `AnimationClip` in the model, and connect it from `entry` to this `Animation State`. You can adjust the transition time from `entry` to this `Animation State` as needed. +Add an `Animation State`. If you're unfamiliar with this process, refer to [Play Animation in Model](/docs/animation/examples/playAnimation/). + +Then: +1. Bind the **"shakeHead"** `AnimationClip` from the model +2. Connect it from `entry` to this `Animation State` +3. Adjust the transition time as needed🧰 Tools
🪛 LanguageTool
[typographical] ~40-~40: Do not use a colon (:) before a series that is introduced by a preposition (‘to’). Remove the colon or add a noun or a noun phrase after the preposition.
Context: ... don't know how to add it, please refer to: [Play Animation in Model](/docs/animati...(RP_COLON)
55-55: Enhance clarity of the blending behavior explanation.The explanation about invalid AnimatorState could be clearer.
-We can see that the `AnimatorState` added in the `Base` animation layer are all invalid because the blending mode is `Override`, which will override all the `Animation Layers` below it. We can adjust the weight of `Layer1` to see the impact of the weight. +When the blending mode is set to `Override`, the `AnimatorState` in `Layer1` completely overrides the animations in the `Base` layer below it. By adjusting the weight of `Layer1`, we can control how much of this override is applied.docs/en/animation/layer.mdx (1)
8-8: Consider restructuring the introduction for better flow.The introduction contains multiple technical terms that could be introduced more gradually.
-`AnimatorControllerLayer` ([API](/apis/core/#AnimatorControllerLayer)) is used to organize and manage `AnimatorStateMachine` ([see details](/docs/animation/state-machine/)) in an `Animation Controller` ([detailed introduction](/docs/animation/animatorController)). Each `AnimatorControllerLayer` has its own `Animation State Machine`. When the `Animation Control Component` runs, all `AnimatorControllerLayer` run simultaneously, controlling the overall animation effect through `blending weight` and `blending mode`. +`AnimatorControllerLayer` ([API](/apis/core/#AnimatorControllerLayer)) is a key component of the animation system that helps organize and manage animations. Each layer: + +- Contains its own `AnimatorStateMachine` ([see details](/docs/animation/state-machine/)) +- Operates within an `Animation Controller` ([detailed introduction](/docs/animation/animatorController)) +- Runs simultaneously with other layers when the animation is played +- Controls the final animation through `blending weight` and `blending mode`docs/en/animation/examples/text-animation.mdx (1)
42-49: Consider adding a visual diagram for the setup process.The callout explains important setup steps but could benefit from a visual representation.
Consider adding a diagram showing the relationship between:
- Entity
- Animator component
- AnimatorController
- Animation State
- AnimationClip
This would help users better understand how these components work together.docs/en/animation/animatorController.mdx (2)
9-9: Consider rephrasing for conciseness.The explanation could be more concise while maintaining clarity.
-The `AnimatorController` ([API](/apis/core/#AnimatorController)) helps you organize a set of animations for a character or other animated object. It visualizes the animation playback logic of animated objects like a flowchart through the `AnimatorStateMachine` ([detailed introduction](/docs/animation/state-machine/)) and automatically switches `AnimatorState` and plays the referenced `AnimationClips` ([detailed introduction](/docs/animation/clip/)) when conditions are met. +The `AnimatorController` ([API](/apis/core/#AnimatorController)) organizes animations for characters or animated objects. Using `AnimatorStateMachine` ([docs](/docs/animation/state-machine/)), it manages animation flow and automatically switches between `AnimatorState`s to play `AnimationClips` ([docs](/docs/animation/clip/)) based on conditions.
13-13: Fix grammatical issue in AnimatorControllerLayer description.The sentence structure needs improvement.
-`AnimatorControllerLayer` are used to organize and manage `AnimatorStateMachines` within an `AnimatorController`. Each `AnimatorControllerLayer` has its own `AnimatorStateMachine`. When the `Animator` component runs, all `AnimatorControllerLayer` run simultaneously, and multiple `AnimatorControllerLayer` achieve animation blending through different weights and blending modes. For detailed usage of `AnimatorControllerLayer`, please refer to the [AnimatorControllerLayer](/docs/animation/layer/) document. +`AnimatorControllerLayer`s organize and manage `AnimatorStateMachines` within an `AnimatorController`. Each layer has its own `AnimatorStateMachine`. When the `Animator` component runs, all layers execute simultaneously and achieve animation blending through weights and blending modes. For detailed usage, refer to the [AnimatorControllerLayer](/docs/animation/layer/) document.docs/en/animation/examples/crossFade.mdx (1)
9-10: Enhance the introduction to better engage readers.Consider adding a brief example or use case to make the introduction more engaging.
-This example demonstrates how to achieve animation transitions in the Galacean editor. Through simple steps, you will learn how to transition from one animation to another. +This example demonstrates how to create smooth animation transitions in the Galacean editor. Learn how to blend animations seamlessly, such as transitioning a character from idle to walking, or walking to running. Through simple steps, you'll master the art of fluid animation transitions.docs/en/animation/examples/material-animation.mdx (1)
81-82: Clarify the keyframe explanation.The explanation about setting keyframes for color transitions could be more detailed.
-3. Set the color property of the `material` in the `MeshRenderer` component to green and blue at `0:20` and `0:40`, respectively. At `1:00`, set it back to red. The first and last keyframes are the same, so the animation can loop naturally. Click the play button to preview this `AnimationClip`. +3. Create a color transition sequence by setting keyframes: + - At `0:20`: Set the color to green + - At `0:40`: Set the color to blue + - At `1:00`: Set the color back to red (matching the first keyframe) + + By making the first and last keyframes identical, the animation creates a seamless loop. Click the play button to preview the color transition `AnimationClip`.docs/en/animation/examples/reuseAnimation.mdx (1)
78-78: Improve sentence variety.The phrase "we need to" is used repeatedly in nearby sentences.
-We find that the `Animator` component is on the `mixamorig:Hips` entity of the animation model, so we need to add the `Animator` component to the `mixamorig:Hips` entity of the character model. +Since the `Animator` component is located on the `mixamorig:Hips` entity of the animation model, add a corresponding `Animator` component to the `mixamorig:Hips` entity of the character model.🧰 Tools
🪛 LanguageTool
[style] ~78-~78: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...sentity of the animation model, so we need to add theAnimatorcomponent to themi...(REP_NEED_TO_VB)
docs/en/animation/animator.mdx (1)
156-156: Remove unnecessary comma for better readability.The comma before "so that" should be removed as it interrupts the natural flow of the sentence.
-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. +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.🧰 Tools
🪛 LanguageTool
[typographical] ~156-~156: The conjunction “so that” does not have a comma in front.
Context: ...nimation will still be updated over time, so that it is correctly displayed when it becom...(SO_THAT_UNNECESSARY_COMMA)
docs/en/animation/examples/controlAnimationByInput.mdx (1)
82-98: Add error handling for input states.The current implementation doesn't handle edge cases where input states might be undefined or invalid.
onUpdate(deltaTime: number) { const inputManager = this.engine.inputManager; + if (!inputManager) { + console.warn('Input manager not available'); + return; + } if (inputManager.isKeyHeldDown(Keys.KeyW)) { if (inputManager.isKeyHeldDown(Keys.ShiftLeft)) { this.animator.setParameterValue('speed', 6); } else { this.animator.setParameterValue('speed', 1); } } if (inputManager.isKeyUp(Keys.KeyW)) { this.animator.setParameterValue('speed', 0); } }docs/en/animation/examples/sprite-sheet.mdx (1)
15-16: Add sprite sheet requirements specification.The documentation should specify recommended sprite sheet dimensions and format requirements.
Add a note about recommended specifications:
Before starting, we need to have the sequence frame images required for creating frame animations. Both sprite sheets and single-frame images can be used. This example uses a sprite sheet. If you don't have one, you can download the [sprite sheet](https://mdn.alipayobjects.com/huamei_3zduhr/afts/img/A*DmSyQZQCnrEAAAAAAAAAAAAADsJ_AQ/original) here. + +> Note: For optimal performance, sprite sheets should: +> - Use power-of-two dimensions (e.g., 512x512, 1024x1024) +> - Be in PNG format for transparency support +> - Have consistent frame sizes within the sheetdocs/en/animation/clip.mdx (1)
209-214: Add validation for animation event parameters.The animation event example should include parameter validation.
const event = new AnimationEvent(); +if (typeof functionName !== 'string' || functionName.trim() === '') { + throw new Error('Invalid function name for animation event'); +} event.functionName = "test"; +if (time < 0 || time > 1) { + throw new Error('Event time must be between 0 and 1'); +} event.time = 0.5; clip.addEvent(event);docs/en/animation/state-machine.mdx (1)
87-99: Add state validation in transition setup.The state transition setup should include validation for state existence and parameter values.
+if (!walkClip || !runClip) { + throw new Error('Animation clips must be defined before creating states'); +} const walkState = animatorStateMachine.addState('walk'); walkState.clip = walkClip; const runState = animatorStateMachine.addState('run'); runState.clip = runClip; const transition = new AnimatorStateTransition(); +if (duration <= 0) { + throw new Error('Transition duration must be positive'); +} transition.duration = 1; transition.offset = 0; +if (exitTime < 0 || exitTime > 1) { + throw new Error('Exit time must be between 0 and 1'); +} transition.exitTime = 0.5; transition.destinationState = runState; walkState.addTransition(transition); animator.play("walk");
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (16)
docs/en/animation/animator.mdx(1 hunks)docs/en/animation/animatorController.mdx(1 hunks)docs/en/animation/clip.mdx(4 hunks)docs/en/animation/examples/blending.mdx(1 hunks)docs/en/animation/examples/controlAnimationByInput.mdx(1 hunks)docs/en/animation/examples/crossFade.mdx(1 hunks)docs/en/animation/examples/material-animation.mdx(1 hunks)docs/en/animation/examples/playAnimation.mdx(1 hunks)docs/en/animation/examples/reuseAnimation.mdx(1 hunks)docs/en/animation/examples/sprite-sheet.mdx(1 hunks)docs/en/animation/examples/text-animation.mdx(1 hunks)docs/en/animation/layer.mdx(1 hunks)docs/en/animation/overview.mdx(1 hunks)docs/en/animation/state-machine.mdx(9 hunks)docs/zh/animation/animator.mdx(1 hunks)docs/zh/animation/examples/reuseAnimation.mdx(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- docs/zh/animation/animator.mdx
🧰 Additional context used
🪛 LanguageTool
docs/en/animation/examples/reuseAnimation.mdx
[style] ~78-~78: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...sentity of the animation model, so we need to add theAnimatorcomponent to themi...
(REP_NEED_TO_VB)
docs/en/animation/clip.mdx
[grammar] ~112-~112: There seems to be a noun/verb agreement error. Did you mean “adds” or “added”?
Context: ...AAAAAAAAAADsJ_AQ/original" /> 2. Click add property, and you can see that the prop...
(SINGULAR_NOUN_VERB_AGREEMENT)
[uncategorized] ~123-~123: Consider adding a hyphen.
Context: ...ve editing. Click the curve icon in the upper right corner to switch. <Image src="https://...
(TOP_LEFT_CORNER)
docs/en/animation/examples/blending.mdx
[typographical] ~40-~40: Do not use a colon (:) before a series that is introduced by a preposition (‘to’). Remove the colon or add a noun or a noun phrase after the preposition.
Context: ... don't know how to add it, please refer to: [Play Animation in Model](/docs/animati...
(RP_COLON)
[style] ~58-~58: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...KITqSUAAAAAAAAAAAAADsJ_AQ/original" /> We can see that as the weight decreases, t...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
docs/en/animation/examples/sprite-sheet.mdx
[uncategorized] ~65-~65: Loose punctuation mark.
Context: ..., 1/3, and 2/3, respectively. Sprite1: <Image src="https://mdn.alipayobjects....
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~69-~69: Loose punctuation mark.
Context: ...AAAAAAAAAADsJ_AQ/original" /> Sprite2: <Image src="https://mdn.alipayobjects....
(UNLIKELY_OPENING_PUNCTUATION)
docs/en/animation/examples/controlAnimationByInput.mdx
[style] ~42-~42: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ... transitions based on user input, so we need to add a Transition Condition. 1. In th...
(REP_NEED_TO_VB)
[style] ~48-~48: This phrasing could be wordy, so try replacing it with something more concise.
Context: ...onditionmeets our needs. Whenspeedis greater than 0, it will transition fromidletow...
(MORE_THAN_EXCEEDS)
[style] ~50-~50: This phrasing could be wordy, so try replacing it with something more concise.
Context: ...ition from walk to run when speed is greater than 5. <Image src="https://mdn.alipayobjec...
(MORE_THAN_EXCEEDS)
docs/en/animation/state-machine.mdx
[uncategorized] ~29-~29: Loose punctuation mark.
Context: ... as the character's Idle state. any: Allows any state in the AnimatorStateMa...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~35-~35: Loose punctuation mark.
Context: ...der clear conditions. exit: Represents the exit point of the Animat...
(UNLIKELY_OPENING_PUNCTUATION)
docs/en/animation/overview.mdx
[style] ~36-~36: ‘blend together’ might be wordy. Consider a shorter alternative.
Context: ...ly and when animations should change or blend together. You can learn how to use it in this [...
(EN_WORDINESS_PREMIUM_BLEND_TOGETHER)
docs/en/animation/animator.mdx
[typographical] ~156-~156: The conjunction “so that” does not have a comma in front.
Context: ...nimation will still be updated over time, so that it is correctly displayed when it becom...
(SO_THAT_UNNECESSARY_COMMA)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: codecov
- GitHub Check: e2e (22.x)
🔇 Additional comments (5)
docs/en/animation/overview.mdx (2)
8-8: LGTM! Clear and concise introduction.The introduction effectively outlines the key features of the animation system.
42-42: LGTM! Clear reference to documentation.The link to the Animator documentation is well-placed and helpful.
docs/zh/animation/examples/reuseAnimation.mdx (1)
83-83: LGTM! Clear instruction in Chinese.The instruction for replacing the animation controller property is clear and consistent with the English documentation.
docs/en/animation/layer.mdx (1)
51-60: LGTM! Clear code example.The TypeScript example effectively demonstrates how to use the API.
docs/en/animation/examples/text-animation.mdx (1)
72-76: LGTM! Clear step-by-step instructions with timing.The instructions for setting keyframes are precise and easy to follow.
Please check if the PR fulfills these requirements
What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)
What is the current behavior? (You can also link to an open issue here)
What is the new behavior (if this is a feature change)?
Does this PR introduce a breaking change? (What changes might users need to make in their application due to this PR?)
Other information:
Summary by CodeRabbit