Skip to content

Custom Animations

You can create new animations by adding JSON files to config/masuholograms/animations/. The filename (without .json) becomes the animation name used in hologram lines. Use only letters, digits and _ in the name: a file such as fire-wave.json loads, but {#ANIM:fire-wave} never matches.

Creating a Custom Animation

Step 1: Create a JSON File

Create a new file in config/masuholograms/animations/. For example, my_animation.json:

{
  "type": "colors",
  "speed": 10,
  "pause": 0,
  "colors": ["&c", "&4"]
}

Step 2: Reload

/mh reload

Step 3: Use It

/mh line set myHolo 1 1 {#ANIM:my_animation}Pulsing Red Text{/#ANIM}

The animation name is the filename without the .json extension.

Missing Fields and Invalid Files

  • A field left out of the file uses: type = frames, speed = 3, pause = 0. Color fields fall back to the defaults listed per type below.
  • A file is rejected (with an error in the server log naming the reason) when speed is below 1, pause is negative, colors, gradientColors or frames is an empty list, or a frames animation has no frames list. The other animations still load.

In the tables below, the Default column for speed and pause shows the value in the generated file of that name.

Animation Types Reference

typewriter

Characters reveal one at a time.

{
  "type": "typewriter",
  "speed": 3,
  "pause": 20
}
Field Type Default Description
speed int 3 Ticks between each character reveal
pause int 20 Extra steps holding the full text (each lasts speed ticks)

wave

Color array sweeps across text left to right.

{
  "type": "wave",
  "speed": 2,
  "pause": 40,
  "colors": ["&e", "&6", "&c", "&4", "&c", "&6"],
  "defaultColor": "&f"
}
Field Type Default Description
speed int 2 Ticks between wave movement
pause int 40 Extra steps holding the text in defaultColor between waves
colors string[] ["&e","&6","&c","&4","&c","&6"] Wave color gradient
defaultColor string "&f" Color for characters not in the wave

burn

Gradient sweep with persistent trail color.

{
  "type": "burn",
  "speed": 2,
  "pause": 40,
  "gradientColors": ["&e", "&6", "&c", "&4"],
  "trailColor": "&4",
  "defaultColor": "&f"
}
Field Type Default Description
speed int 2 Ticks between burn movement
pause int 40 Extra steps holding the burnt text (each lasts speed ticks)
gradientColors string[] ["&e","&6","&c","&4"] Burn front colors
trailColor string "&4" Color left after burn passes
defaultColor string "&f" Color of unburned text

scroll

Text rotates horizontally.

{
  "type": "scroll",
  "speed": 3,
  "pause": 0
}
Field Type Default Description
speed int 3 Ticks between each shift
pause int 0 Extra steps holding the unshifted text after each full turn

colors

Entire text cycles through a color array.

{
  "type": "colors",
  "speed": 4,
  "pause": 0,
  "colors": ["&c", "&6", "&e", "&a", "&b", "&9", "&d"]
}
Field Type Default Description
speed int 4 Ticks between color changes
pause int 0 Extra steps holding the last color
colors string[] rainbow Color sequence

frames

Explicit text frames - the most flexible type.

{
  "type": "frames",
  "speed": 20,
  "pause": 0,
  "frames": [
    "&aFrame one text",
    "&bFrame two text",
    "&cFrame three text"
  ]
}
Field Type Default Description
speed int 5 Ticks between frame changes
pause int 0 Extra steps holding the last frame (each lasts speed ticks)
frames string[] Required List of frame text

With frames, the original text between animation tags is completely replaced by each frame's text. Each frame can have its own colors and content.

Example Custom Animations

Slow Pulse (2 colors)

File: pulse_red.json

{
  "type": "colors",
  "speed": 10,
  "pause": 0,
  "colors": ["&c", "&4"]
}

Usage: {#ANIM:pulse_red}ALERT{/#ANIM}

Ice Wave

File: ice_wave.json

{
  "type": "wave",
  "speed": 2,
  "pause": 0,
  "colors": ["&f", "&b", "&3", "&9", "&3", "&b"],
  "defaultColor": "&7"
}

Nether Burn

File: nether_burn.json

{
  "type": "burn",
  "speed": 1,
  "pause": 20,
  "gradientColors": ["&e", "&6", "&c", "&4", "&0"],
  "trailColor": "&8",
  "defaultColor": "&f"
}

Status Indicator

File: status_online.json

{
  "type": "frames",
  "speed": 20,
  "pause": 0,
  "frames": [
    "&a● &fOnline",
    "&2● &fOnline"
  ]
}

Usage: {#ANIM:status_online}ignored{/#ANIM}

Countdown

File: countdown.json

{
  "type": "frames",
  "speed": 20,
  "pause": 2,
  "frames": [
    "&c3",
    "&e2",
    "&a1",
    "&b&lGO!"
  ]
}

Emoji Spinner

File: spinner.json

{
  "type": "frames",
  "speed": 5,
  "pause": 0,
  "frames": [
    "&6|",
    "&6/",
    "&6-",
    "&6\\"
  ]
}

News Ticker

File: slow_scroll.json

{
  "type": "scroll",
  "speed": 2,
  "pause": 0
}

Usage: {#ANIM:slow_scroll}BREAKING NEWS: Server reset at midnight! {/#ANIM} (the trailing spaces make the gap; commands typed in game lose repeated and trailing spaces (Minecraft collapses them in chat), so add the gap from the server console or in the hologram file)

Color Codes in JSON

All color codes in JSON files use & notation (not §). The mod automatically converts & to § when loading the file.

Supported in JSON:

  • &0 through &f - legacy colors
  • &k, &l, &m, &n, &o - formatting
  • &r - reset

Warning

Hex colors (&#RRGGBB), gradients (<GRADIENT:...>), and rainbow (<RAINBOW>) are not supported inside animation JSON color arrays. Use only legacy & codes in animation configuration files. In frames, every & is turned into a color code too, so &#RRGGBB does not work there either; <GRADIENT:...> and <RAINBOW> tags inside a frame do work.

Tips

  • Test with high speed first (speed: 1) to quickly see how the animation looks, then slow it down
  • Use pause to give viewers time to read completed animations
  • Frame-based animations are the most versatile - you can create any effect by listing explicit frames
  • File names are animation names - use descriptive names like fire_wave, team_pulse, alert_blink
  • Run /mh reload after editing any animation file