Skip to content

Animation Overview

MasuHolograms features a fully file-based animation system. All animations are defined as JSON files in config/masuholograms/animations/. You can modify the default animations and create entirely new ones.

How Animations Work

Animations cycle through visual states. The speed parameter controls how many ticks pass between two animation steps. The pause parameter adds extra steps at the end of a cycle before it restarts; each step lasts speed ticks, so speed: 3 with pause: 20 holds for 60 ticks (3 seconds). During the pause each type holds its rest state: the full text (typewriter, scroll), the burnt text (burn), the text in its default color (wave), or the last color or frame (colors, frames).

The animation system processes text within {#ANIM:name}...{/#ANIM} tags, replacing the content with the animated version based on the current step.

Animation Syntax

Standard Syntax

{#ANIM:animationName}Your text here{/#ANIM}

Alternative Syntax

<#ANIM:animationName>Your text here</#ANIM>

Both syntaxes are equivalent. Use whichever you prefer.

Color Shortcut

The &u code is a shortcut for the colors animation:

&uRainbow cycling text

This is equivalent to {#ANIM:colors}Rainbow cycling text{/#ANIM}, except &u applies to the rest of the line (no closing tag needed).

Animation Parameters

All animation types share these parameters:

Parameter Type Default Description
type string frames Animation algorithm (typewriter, wave, burn, scroll, colors, frames)
speed int 3 Ticks between animation steps (higher = slower), at least 1
pause int 0 Extra steps at the end of a cycle, not negative

The defaults apply to fields left out of a file. A file with an invalid value is rejected with an error in the server log; see Custom Animations.

Additional parameters depend on the animation type. See Built-in Animations and Custom Animations.

Using Animations

In Commands

/mh line set myHolo 1 1 &6{#ANIM:typewriter}Welcome to the Server!{/#ANIM}
/mh line set myHolo 1 1 {#ANIM:wave}Colorful Wave Effect{/#ANIM}
/mh line set myHolo 1 1 &uRainbow Color Cycling

Colors and Formatting

An animation works on the characters between its tags, so keep that text plain and put color codes in front of the opening tag:

  • typewriter and scroll keep the color written before the tag (&6{#ANIM:typewriter}...). A code inside the tag can be cut in half for a step and show as text.
  • wave and burn give every character its own color, so codes inside the tag show as text, and a color or format code before the tag is replaced. For bold or other formatting, make a custom animation whose colors carry it, for example "colors": ["&e&l", "&6&l"] with "defaultColor": "&f&l".
  • colors (and &u) put one color in front of the text; format codes after it, inside the tag, still work.

With Placeholders

By default the animation runs on the raw text and placeholders are resolved in each frame afterwards. A placeholder the animation keeps whole works (colors, frames), but typewriter shows half-typed tokens such as {onl while typing, and wave and burn split every token so it shows as text. To resolve placeholders first and animate the result, enable this in config.json:

{
  "allowPlaceholdersInsideAnimations": true
}

Then you can use:

/mh line set myHolo 1 1 {#ANIM:typewriter}Online: {online}/{max_players}{/#ANIM}

Multiple Animations Per Line

You can have multiple animation segments in a single line:

/mh line set myHolo 1 1 {#ANIM:wave}Hello{/#ANIM} &7- {#ANIM:colors}World{/#ANIM}

Disabling Animations

Per Hologram

/mh hologram addflag myHolo DISABLE_ANIMATIONS

Per Line

/mh line addflag myHolo 1 1 DISABLE_ANIMATIONS

Globally

Animations are always active unless disabled via flags. There is no global disable toggle - use flags on individual holograms.

File Location

All animation files live in:

config/masuholograms/animations/

On first startup (and whenever the folder has no .json file), 6 default animation files are generated. You can modify these or add new ones. Run /mh reload after making changes.

Next Steps