DOCSEARCHbyAlgolia
Submit Docs

BetterAnimations Documentation

website·Indexed 30 days ago

https://docs.betteranimations.net

A client mod and framework for creating dynamic animations in Discord. It utilizes the Anime JavaScript Animation Engine and provides a system for building reusable snippets, packs, and overridables. The documentation covers the animation lifecycle, parsing, layout, and a variety of 'injects' for math, objects, arrays, and general utility to facilitate complex animation implementations.

Tokens
25.5K
Snippets
170
Records
229
Agent score
49%

What's inside BetterAnimations

  1. Understand the BetterAnimations layout structure

    Every animation in a Module uses a base layout consisting of an Element and a Container.

    • Element: The actual DOM element that the animation targets to make appear (enter) or disappear (exit). All visual styles should be applied here.
    • Container: A wrapper element around the Element. It is used to define a containing block and stacking context, implement overflow settings (via clip), and facilitate Accordion animations without affecting the Element's size or position.

  2. Understand BetterAnimations core concepts: Animations and Modules

    BetterAnimations is built on two primary entities:

    1. Animations: Define how an element appears or disappears. Every Animation consists of an Enter animation (for appearance) and an Exit animation (for disappearance).
    2. Modules: Control which parts of Discord are animated (e.g., Servers, Channels, Popouts, Messages). Modules fall into two types:
      • Reveal: Animate elements that appear and disappear independently (e.g., opening a User Card popout or a new message being sent).
      • Switch: Animate the transition between elements sharing the same container (e.g., switching between different Discord servers or settings sections).

  3. Understand Animation Intersections in BetterAnimations

    BetterAnimations intersects Animation instances to create seamless transitions between unfinished Enter and Exit animations. Intersection occurs only when the following conditions are met: the Module type is Reveal, and the Animation, Module, and Element are identical for both Animation instances.

  4. Define an Animate execution object

    An Animate object is the execution definition of an Animation. It must be defined within the animate property, or the enter and exit properties of an Animation. All hooks and properties within an Animate definition are injectable and can accept nested arrays or null for extensibility.

  5. Understand Internal vs. Implemented Accordions

    BetterAnimations provides two ways to handle Expand/Collapse (Accordion) animations:

    1. Internal Accordions: Enabled by default for animations. These execute sequentially: first before the main animation and then after it.
    2. Implemented Accordions: Custom animations applied to layout properties (margin, width, height) of a Container. These execute simultaneously with the rest of the animation.

  6. Understand how Switch Animations function

    Switch Animations are standard Animations executed within Modules of type 'Switch'. Unlike linear animations, a Switch Animation triggers two processes in parallel during a transition: the Exit animation for the current module and the Enter animation for the target module. This simultaneous execution creates the visual effect of a single seamless transition.

  7. Publish an animation pack to the Catalog

    To make your animation pack available for the community to download and use via the Catalog, follow these steps:

    1. Ensure your pack adheres to the publishing guidelines.
    2. Host your pack in a GitHub repository.
    3. Submit the repository link to the developer via Discord (username arg0nny or the Support Server) or Telegram (@okdevme).

  8. Use override presets in Meta definitions

    Some Overridables provide presets that encapsulate a set of common overrides. You can apply a preset by adding it to the override array using the preset key. Presets can be combined with additional custom overrides.
    {
  "meta": {
    "override": [
      { "preset": "accordion" }, 
      {
        "for": {
          "type": "enter"
        },
        "intersect": false
      }
    ]
  }
}

  9. Prerequisites for creating BetterAnimations

    To author custom animations for BetterAnimations, developers should have a basic understanding of JavaScript, HTML, CSS, and JSON. It is also recommended to be familiar with the general usage of BetterAnimations as a user before attempting to create animations.

  10. Understand the animation extension lifecycle

    The extension process occurs during the first step of the Animation Lifecycle, called Perform extend.

    Key characteristics of the extension process:

    1. Recursive Extension: If an animation extends a definition that itself extends another definition, the process continues recursively until no more extensions are found.
    2. beforeExtend Hook: A specific hook called beforeExtend is triggered before the extends property is parsed. This allows developers to attach callbacks to modify the animation before the extension logic is applied.

  11. Detect enabled BetterAnimations modules via CSS

    BetterAnimations adds a specific class to the root html element of the Discord app whenever a module is enabled. This allows theme developers to apply conditional style overrides using the pattern .BA__module_{key}, where {key} is the unique ID of the module.
    /* Example: Override styles only when the Servers module is enabled */
.BA__module_servers .yourClass {
    /* your override styles here */
}

  12. Build composite animations using load and extends

    You can create composite animations by extending existing animations. Use the load inject to retrieve the raw Animate definition of another animation by its key. The extends property can accept a single animation definition or an array of definitions to merge multiple animations into one.
    {
  "key": "scaleSlip",
  "name": "Scale + Slip",
  "animate": {
    "extends": [
      {
        "inject": "load",
        "animation": "scale"
      },
      {
        "inject": "load",
        "animation": "slip"
      }
    ]
  }
}