Documented the 'extra keyframes' feature. Close #122.

Author: Nusiq

docs/animations/exporting_animations.md

@@ -16,6 +16,7 @@ The `Optimize Animation` checkbox allows you to apply **lossy** optimization to
 
 Exporting a single animation is similar to exporting a model, as explained in the {ref}`Creating animations from scratch<creating-animations-from-scratch>` documentation page. Go to `File > Export > Export Bedrock Animation` and select the export path. If the file already exists and is a valid animation file, the exported animation will be appended/updated.
 
+(batch-exporting-multiple-animations)=
 ## Batch exporting multiple animations
 
 If your armature contains several animations you can export **all of them at once** using the *Batch Export Bedrock Animations* operator:

docs/animations/extra_keyframes.md

@@ -0,0 +1,35 @@
+(extra-keyframes)=
+# Extra Keyframes
+
+The Extra Keyframes feature in Mcblend allows you to add additional keyframes to your exported animations. This is especially valuable when your model's animation is driven by constraints, physics simulations, or other procedural methods that don't place keyframes on the armature's timeline. Mcblend can then capture these dynamic poses at specified frames without requiring you to manually keyframe them. This feature deosn't replace explicitly set timeline keyframes; instead, it supplements them
+
+Extra Keyframes complement the {ref}`Animation Optimization<optimizing-animations>` feature; they add extra detail to exported animations, while the optimization removes redundant keyframes.
+
+![](/img/animations/object_properties_animations_extra_frames.png)
+
+## How it Works
+
+In the `Mcblend: Animations` panel (found in `Object Properties` when an Armature is selected), you'll find an "Extra frames" field. This field accepts a pattern string that defines individual frames or ranges of frames to be added to the animation during export.
+
+### Frame Range Patterns
+
+The patterns use a colon-separated and comma-separated format, based on the following rules:
+
+- `START:END` - Includes all integer frames from `START` to `END` (inclusive).
+- `START:STEP:END` - Includes frames from `START` to `END`, incrementing by `STEP`.
+- `FRAME` - Includes a single, specific frame.
+- `START:` - Includes all frames from `START` to the end of the animation (as defined by the "Frame end" property of the animation).
+- `START:STEP:` - Includes all frames from `START` to the end of the animation, incrementing by `STEP`.
+- You can combine multiple patterns by separating them with commas.
+
+Examples:
+- `1:10` adds frames 1, 2, 3, 4, 5, 6, 7, 8, 9, 10.
+- `1:2:10` adds frames 1, 3, 5, 7, 9.
+- `15` adds frame 15.
+- `50:` adds all frames from 50 to the animation's end.
+- `1:2:` adds frames 1, 3, 5, ... up to the animation's end.
+- `1:5, 10:2:20, 25, 27:` would include frames 1 through 5, then 10, 12, 14, 16, 18, 20, then frame 25, and finally frames 27, 28, 29... up to the animation's end.
+
+## Interpolation
+
+It's important to note that all keyframes added via the "Extra frames" feature will use **linear interpolation** in the exported Minecraft animation.

docs/animations/physics_simulation.md

@@ -54,18 +54,21 @@ The `Bone Parents` group never needs to be adjusted.
 ![](/img/animations/physics_simulation_bake_menu.png)
 ![](/img/animations/physics_simulation_bake_settings.png)
 
-7. The keyframes added by the `Bake to Keyframes` operation are not sufficient to properly export the animation. Mcblend requires keyframes to be added to the armature of the model, but the keyframes from the simulation are added to the rigid bodies.
+7. The keyframes generated by the `Bake to Keyframes` operation are insufficient for proper animation export. Mcblend requires keyframes to be applied to the model's armature, whereas the simulation applies them to rigid bodies.
 
-To successfully export the animation, you will need to manually add keyframes to the armature of the model. The movements of the simulation are complex, so you will need to add one keyframe for each frame of the simulation, approximately 50 frames in total. Mcblend does not currently have an automatic method for adding these keyframes, so you will need to do it manually. It doesn't matter what kind of keyframe you add - Mcblend uses the keyframes as points in the timeline that mark an important event in the animation, and then analyzes the pose of the model to compare it to the previous point in the animation.
+Fortunately, you do not need to manually add all 50 keyframes. Mcblend can automate this process during animation export. Simply {ref}`create a new empty Mcblend animation<creating-animations-from-scratch>` and utilize the {ref}`Extra Keyframes<extra-keyframes>` feature to add keyframes starting from frame 1 (define the range as `1:`).
 
-We can simply add the `Scale` keyframes to the root bone. It doesn't matter that the scale is the same on every frame, the important thing is that the keyframes are there.
-
-![](/img/animations/physics_simulation_ravager_scale_keyframes.png)
+```{warning}
+If a warning prompts you to "Stash or push down" before adding a new animation when pressing the `New Animation` button, select `Push down` in the `Action Editor` tab. This action moves the current animation to the `Nonlinear Animation` editor while keeping it active.
+```
 
-8. For better results, before exporting select all the keyframes and change the interpolation mode to `Linear`. You can access the interpolation mode menu by right clicking in the `Dope Sheet` editor.
+Before exporting, make sure that frame 0 is a rest pose and that all bone transformations at that frame are keyframed.
 
-9. [Export the animation](/animations/exporting_animations) using the knowledge from previous tutorials.
+To reduce animation size with a minimal impact on quality, consider using the `{ref}Animation Optimization<optimizing-animations>` feature.
 
 ![](/img/animations/physics_simulation_export_animation.png)
 
+9. [Export the animation](/animations/exporting_animations) using the knowledge from previous tutorials.
+
+Result:
 ![](/img/animations/physics_simulation_ravager.gif)

docs/gui/object_properties.md

@@ -54,21 +54,22 @@ Once you've set up your render controller, you can use the `Apply materials` but
 
 The `Mcblend: Animations panel` allows you to easily switch between animations in your project. These animations are represented as NLA tracks on the armature, with additional data attached to them. Selecting a different animation in the panel will also switch the active NLA track.
 
-- The `New animation` button creates a new animation. You can't use this operator while editing an action of the armature. If you want to create a new action, you need to stash the other action first.
-- The `Remove animation` button removes the currently active animation.
-- The `Select animation` dropdown list lets you select the animation to edit.
-- The `Name` field sets the name of the animation.
-- The `Skip rest poses` checkbox enables animation export optimization. If enabled, the keyframes that don't affect the armature (because they are the rest poses) are skipped in the exported file. In most cases, it's recommended to enable this option.
-- The `Export as pose` checkbox, if enabled, causes the exported animation to contain only one looped frame.
-- The `Exclude from batch exports` checkbox, if enabled, causes the animation to be skipped when using the `Batch Export Bedrock Animations` operator. Alternatively, you can select which animations to export during the export process.
-- The `Override previous animation` field directly translates to the override_previous_animation property of the Minecraft animation. It doesn't affect how the animation is rendered in Blender.
-- The `Loop` field directly translates to the loop property of the Minecraft animation file. There are three options: `true`, `false`, and `hold_on_last_frame`.
-- The `Anim Time Update` field directly translates to the anim_time_update property of the Minecraft animation file. You should either leave it empty (if you don't want to have anim_time_update in your animation) or put a Molang expression in it. It doesn't affect the animation in Mcblend because Mcblend doesn't support Molang.
-- The `Interpolation mode` field directly translates to the interpolation mode of the Minecraft animation file. There are four options: `linear`, `smooth`, `step`, and `auto`.
-- The `Frame start` field indicates the first frame of the animation. It tells Mcblend where the animation starts.
-- The `Frame end` field indicates the last frame of the animation. It tells Mcblend where the animation ends.
-- The `Optimize Animation` checkbox enables {ref}`animation export optimization<optimizing-animations>`.
-- The `Error margin` field defines how much error is allowed when optimizing the exported animation.
+- `New animation` - Creates a new animation. This operator cannot be used while editing an action of the armature; you must stash the current action first.
+- `Remove animation` - Deletes the currently active animation.
+- `Select animation` - A dropdown list to choose which animation to edit.
+- `Name` - Sets the name of the animation.
+- `Skip rest poses` - Enables animation export optimization. When enabled, keyframes that represent rest poses (and thus don't affect the armature) are skipped in the exported file. Enabling this option is generally recommended.
+- `Export as pose` - If enabled, the exported animation will contain only a single looped frame.
+- `Exclude from batch exports` - If enabled, this animation will be skipped when using the {ref}`Batch Export Bedrock Animations<batch-exporting-multiple-animations>` operator. Alternatively, you can select animations to export during the export process.
+- `Override previous animation` - Directly translates to the `override_previous_animation` property in the Minecraft animation file. This setting does not affect how the animation is rendered in Blender.
+- `Loop` - Directly translates to the `loop` property of the Minecraft animation file, with options: `true`, `false`, and `hold_on_last_frame`.
+- `Anim Time Update` - Directly translates to the `anim_time_update` property of the Minecraft animation file. Leave this empty if not needed, or provide a Molang expression. Note that Mcblend does not support Molang, so this setting does not affect the animation within Mcblend.
+- `Interpolation mode` - Directly translates to the interpolation mode of the Minecraft animation file, with options: `linear`, `smooth`, `step`, and `auto`. The `auto` option uses the interpolation based on the interpolation modes used for each keyframe.
+- `Extra frames` - Allows you to specify additional frames or frame ranges to be included in the exported animation. Refer to the dedicated {ref}`Extra Keyframes<extra-keyframes>` page for details on patterns and usage.
+- `Frame start` - Indicates the first frame of the animation, defining its starting point in Mcblend.
+- `Frame end` - Indicates the last frame of the animation, defining its end point in Mcblend.
+- `Optimize Animation` - Enables {ref}`animation optimization<optimizing-animations>` during export.
+- `Error margin` - Defines how much error is allowed when optimizing the exported animation.
 
 ## Object properties (bone of armature)
 

docs/img/animations/object_properties_animations_extra_frames.png

@@ -40,6 +40,7 @@ Essential concepts for creating animations in Mcblend <animations/essential_conc
 Creating animations from scratch <animations/creating_animations_from_scratch>
 Exporting animations <animations/exporting_animations>
 Optimizing animations <animations/optimizing_animations>
+Extra keyframes <animations/extra_keyframes>
 Animating sound and particle effects <animations/animating_sound_and_particle_effects>
 Physics simluation <animations/physics_simulation>
 ```