wiki: Add animations page

3 files changed, 155 insertions, 73 deletions

diff --git a/resources/default-config.kdl b/resources/default-config.kdl
index 28833919..79eaef12 100644
--- a/resources/default-config.kdl
+++ b/resources/default-config.kdl
@@ -223,85 +223,14 @@ hotkey-overlay {
 }
 
 // Animation settings.
+// The wiki explains how to configure individual animations:
+// https://github.com/YaLTeR/niri/wiki/Configuration:-Animations
 animations {
     // Uncomment to turn off all animations.
     // off
 
     // Slow down all animations by this factor. Values below 1 speed them up instead.
     // slowdown 3.0
-
-    // You can configure all individual animations.
-    // Available settings are the same for all of them.
-    // - off disables the animation.
-    //
-    // Niri supports two animation types: easing and spring.
-    // You can set properties for only ONE of them.
-    //
-    // Easing has the following settings:
-    // - duration-ms sets the duration of the animation in milliseconds.
-    // - curve sets the easing curve. Currently, available curves
-    //   are "ease-out-cubic" and "ease-out-expo".
-    //
-    // Spring animations work better with touchpad gestures, because they
-    // take into account the velocity of your fingers as you release the swipe.
-    // The parameters are less obvious and generally should be tuned
-    // with trial and error. Notably, you cannot directly set the duration.
-    // You can use this app to help visualize how the spring parameters
-    // change the animation: https://flathub.org/apps/app.drey.Elastic
-    //
-    // A spring animation is configured like this:
-    // - spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
-    //
-    // The damping ratio goes from 0.1 to 10.0 and has the following properties:
-    // - below 1.0: underdamped spring, will oscillate in the end.
-    // - above 1.0: overdamped spring, won't oscillate.
-    // - 1.0: critically damped spring, comes to rest in minimum possible time
-    //        without oscillations.
-    //
-    // However, even with damping ratio = 1.0 the spring animation may oscillate
-    // if "launched" with enough velocity from a touchpad swipe.
-    //
-    // Lower stiffness will result in a slower animation more prone to oscillation.
-    //
-    // Set epsilon to a lower value if the animation "jumps" in the end.
-    //
-    // The spring mass is hardcoded to 1.0 and cannot be changed. Instead, change
-    // stiffness proportionally. E.g. increasing mass by 2x is the same as
-    // decreasing stiffness by 2x.
-
-    // Animation when switching workspaces up and down,
-    // including after the touchpad gesture.
-    workspace-switch {
-        // off
-        // spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
-    }
-
-    // All horizontal camera view movement:
-    // - When a window off-screen is focused and the camera scrolls to it.
-    // - When a new window appears off-screen and the camera scrolls to it.
-    // - When a window resizes bigger and the camera scrolls to show it in full.
-    // - And so on.
-    horizontal-view-movement {
-        // off
-        // spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
-    }
-
-    // Window opening animation. Note that this one has different defaults.
-    window-open {
-        // off
-        // duration-ms 150
-        // curve "ease-out-expo"
-
-        // Example for a slightly bouncy window opening:
-        // spring damping-ratio=0.8 stiffness=1000 epsilon=0.0001
-    }
-
-    // Config parse error and new default config creation notification
-    // open/close animation.
-    config-notification-open-close {
-        // off
-        // spring damping-ratio=0.6 stiffness=1000 epsilon=0.001
-    }
 }
 
 // Window rules let you adjust behavior for individual windows.
diff --git a/wiki/Configuration:-Animations.md b/wiki/Configuration:-Animations.md
new file mode 100644
index 00000000..5a397de8
--- /dev/null
+++ b/wiki/Configuration:-Animations.md
@@ -0,0 +1,152 @@
+### Overview
+
+Niri has several animations which you can configure in the same way.
+Additionally, you can disable or slow down all animations at once.
+
+Here's a quick glance at the available animations with their default values.
+
+```
+animations {
+    // Uncomment to turn off all animations.
+    // You can also put "off" into each individual animation to disable it.
+    // off
+
+    // Slow down all animations by this factor. Values below 1 speed them up instead.
+    // slowdown 3.0
+
+    // Individual animations.
+
+    workspace-switch {
+        spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
+    }
+
+    horizontal-view-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+
+    window-open {
+        duration-ms 150
+        curve "ease-out-expo"
+    }
+
+    config-notification-open-close {
+        spring damping-ratio=0.6 stiffness=1000 epsilon=0.001
+    }
+}
+```
+
+### Animation Types
+
+There are two animation types: easing and spring.
+Each animation can be either an easing or a spring.
+
+#### Easing
+
+This is a common animation type that changes the value over a set duration using a Bézier curve.
+
+To use this animation, set the following parameters:
+
+- `duration-ms`: duration of the animation in milliseconds.
+- `curve`: the easing curve to use.
+
+Currently, niri only supports two curves: `ease-out-cubic` and `ease-out-expo`.
+You can get a feel for them on pages like [easings.net](https://easings.net/).
+
+#### Spring
+
+Spring animations use a model of a physical spring to animate the value.
+They notably feel better with touchpad gestures, because they take into account the velocity of your fingers as you release the swipe.
+Springs can also oscillate / bounce at the end with the right parameters if you like that sort of thing, but they don't have to (and by default they mostly don't).
+
+Due to springs using a physical model, the animation parameters are less obvious and generally should be tuned with trial and error.
+Notably, you cannot directly set the duration.
+You can use the [Elastic](https://flathub.org/apps/app.drey.Elastic) app to help visualize how the spring parameters change the animation.
+
+A spring animation is configured like this, with three mandatory parameters:
+
+```
+animations {
+    workspace-switch {
+        spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
+    }
+}
+```
+
+The `damping-ratio` goes from 0.1 to 10.0 and has the following properties:
+
+- below 1.0: underdamped spring, will oscillate in the end.
+- above 1.0: overdamped spring, won't oscillate.
+- 1.0: critically damped spring, comes to rest in minimum possible time without oscillations.
+
+However, even with damping ratio = 1.0, the spring animation may oscillate if "launched" with enough velocity from a touchpad swipe.
+
+Lower `stiffness` will result in a slower animation more prone to oscillation.
+
+Set `epsilon` to a lower value if the animation "jumps" at the end.
+
+> [!TIP]
+> The spring *mass* (which you can see in Elastic) is hardcoded to 1.0 and cannot be changed.
+> Instead, change `stiffness` proportionally.
+> E.g. increasing mass by 2× is the same as decreasing stiffness by 2×.
+
+### Animations
+
+Now let's go into more detail on the animations that you can configure.
+
+#### `workspace-switch`
+
+Animation when switching workspaces up and down, including after the vertical touchpad gesture (a spring is recommended).
+
+```
+animations {
+    workspace-switch {
+        spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
+    }
+}
+```
+
+#### `horizontal-view-movement`
+
+All horizontal camera view movement animations, such as:
+
+- When a window off-screen is focused and the camera scrolls to it.
+- When a new window appears off-screen and the camera scrolls to it.
+- When a window resizes bigger and the camera scrolls to show it in full.
+- After a horizontal touchpad gesture (a spring is recommended).
+
+```
+animations {
+    horizontal-view-movement {
+        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
+    }
+}
+```
+
+#### `window-open`
+
+Window opening animation.
+
+This one uses an easing type by default.
+
+```
+animations {
+    window-open {
+        duration-ms 150
+        curve "ease-out-expo"
+    }
+}
+```
+
+#### `config-notification-open-close`
+
+The open/close animation of the config parse error and new default config notifications.
+
+This one uses an underdamped spring by default (`damping-ratio=0.6`) which causes a slight oscillation in the end.
+
+```
+animations {
+    config-notification-open-close {
+        spring damping-ratio=0.6 stiffness=1000 epsilon=0.001
+    }
+}
+```
diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md
index e4180beb..eb451bfd 100644
--- a/wiki/_Sidebar.md
+++ b/wiki/_Sidebar.md
@@ -9,6 +9,7 @@
 * [Overview](./Configuration:-Overview.md)
 * [Input](./Configuration:-Input.md)
 * [Window Rules](./Configuration:-Window-Rules.md)
+* [Animations](./Configuration:-Animations.md)
 
 ## Development
 * [Design Principles](./Design-Principles.md)