Skip to content

Main Config

The main configuration file is located at config/masuholograms/config.json. It is generated on first startup with default values.

After editing, run /mh reload to apply changes.

How the File Is Read

  • On every load the file is written back: keys missing from your file are added with their defaults and unknown keys are removed. Your values are kept.
  • If the file is not valid JSON, the error is logged, your file is left untouched and the defaults are used until you fix it and run /mh reload.
  • The file is written crash-safe (temporary file, then moved into place), like every file of the mod. See Storage & Backups.
  • & and other special characters are written as typed (for example "&c-{damage}"). Hologram files store & as \u0026; both forms mean the same character, so you can write & when you edit either file.

Full Default Config

{
  "configVersion": 2,
  "defaultText": "Blank Line",
  "defaultDisplayRange": 48,
  "defaultUpdateRange": 48,
  "defaultUpdateInterval": 20,
  "defaultDownOrigin": false,
  "defaultTextHeight": 0.3,
  "defaultIconHeight": 0.6,
  "defaultHeadHeight": 0.75,
  "defaultSmallHeadHeight": 0.6,
  "clickCooldownTicks": 5,
  "clickRange": 6.0,
  "allowPlaceholdersInsideAnimations": false,
  "updateVisibilityOnTeleport": false,
  "entityScaleAttribute": "",
  "damageDisplay": {
    "enabled": false,
    "showForPlayers": true,
    "showForMobs": true,
    "showZeroDamage": false,
    "durationTicks": 40,
    "heightOffset": 2.0,
    "format": "&c-{damage}",
    "criticalFormat": "&4&l-{damage}"
  },
  "healingDisplay": {
    "enabled": false,
    "showForPlayers": true,
    "showForMobs": false,
    "durationTicks": 40,
    "heightOffset": 2.0,
    "format": "&a+{healing}"
  },
  "lecternHolograms": {
    "enabled": true,
    "maxLinesPerPage": 6,
    "defaultLimit": 3,
    "maxLimit": 20,
    "heightOffset": 0.0,
    "displayRange": 48,
    "allowColorCodes": true,
    "disablePlaceholders": true,
    "disableAnimations": true,
    "validationIntervalTicks": 100
  },
  "customReplacements": {
    "[x]": "█",
    "[X]": "█",
    "[/]": "▀",
    "[,]": "░",
    "[,,]": "▒",
    "[,,,]": "▓",
    "[p]": "•",
    "[P]": "•",
    "[|]": "⎮"
  }
}

General Settings

configVersion

Default: 2

Managed by the mod; do not change it. Version 2 changed the default of clickCooldownTicks from 1 to 5. When an older file (version 1 or no version) is loaded and still has the old default 1, it is raised to 5 once. Any other value you chose is kept.

defaultText

Default: "Blank Line"

The text used when a line or page is created without content (e.g. /mh line add myHolo 1, /mh page add myHolo, /mh hologram create myHolo).

defaultDisplayRange

Default: 48 Range: 1-256

The display range (in blocks) that newly created holograms start with.

defaultUpdateRange

Default: 48 Range: 1-256

The update range (in blocks) that newly created holograms start with: viewers farther away than this get no placeholder or animation updates.

defaultUpdateInterval

Default: 20 Range: 1-1200

The number of ticks between placeholder refreshes that newly created holograms start with. 20 ticks = 1 second.

defaultDownOrigin

Default: false

Line stacking direction for new holograms.

  • false = top-down (line 1 at the top)
  • true = bottom-up (last line at the origin)

Default Heights

Setting Default For
defaultTextHeight 0.3 Text lines
defaultIconHeight 0.6 Icon (item) lines
defaultHeadHeight 0.75 Head lines
defaultSmallHeadHeight 0.6 Small head lines

Heights must be above 0 and at most 16. Entity lines always default to 1.0 and player (NPC) lines to 2.3; these two have no config key.

Defaults apply to new holograms and lines

The default* keys only set the starting values of new holograms and lines. Saved holograms keep the values in their files. A value outside its range is replaced by the built-in default and named in a warning in the server log.

clickCooldownTicks

Default: 5

Minimum ticks between two counted clicks of the same player, on any hologram. A held right-click repeats every 4 ticks, so the default of 5 keeps a held button from firing the actions again and again. Values below 1 count as 1.

Value Cooldown
1 0.05s (no protection against a held button)
5 0.25s (default)
10 0.5s
20 1s

clickRange

Default: 6.0

How far (in blocks, measured from the player's eyes) a player may be from a hologram for a click to count: from the hologram's origin, any of its lines, or the nearest point of the page's visible height. Clicks from farther away are ignored. See Click Actions.

allowPlaceholdersInsideAnimations

Default: false

When true, placeholders like {player} inside {#ANIM:...}...{/#ANIM} tags are resolved before the animation processes the text.

updateVisibilityOnTeleport

Default: false

When true, a player who teleports gets their hologram visibility checked on the next tick, instead of at the next periodic check (every second).

entityScaleAttribute

Default: "" (empty, disabled)

The attribute used for scaling via /mh line setscale. Applies to both #ENTITY: and #PLAYER: lines. The attribute must be provided by an installed mod.

Example for Vault Hunters:

{
  "entityScaleAttribute": "the_vault:generic.size_scale"
}

When empty, /mh line setscale refuses with an error.

Player lines

For #PLAYER: lines, the scale is applied directly to the Taterzens NPC as a server-side entity attribute. This requires Taterzens to be installed in addition to the mod providing the attribute.

Damage Display

See Damage Display for detailed configuration.

Healing Display

See Healing Display for detailed configuration.

Lectern Holograms

See Lectern Holograms for detailed configuration.

Custom Replacements

Text shortcuts that are replaced before color processing. Keys are the shortcut text, values are the replacement characters.

Default Replacements

Shortcut Character Unicode Description
[x] / [X] █ U+2588 Full block
[/] ▀ U+2580 Upper half block
[,] ░ U+2591 Light shade
[,,] ▒ U+2592 Medium shade
[,,,] ▓ U+2593 Dark shade
[p] / [P] • U+2022 Bullet
[|] ⎮ U+23AE Vertical bar

The file shows the characters themselves; \u2588-style escapes work as well.

Adding Custom Replacements

Add entries to the customReplacements object. Use Unicode escape sequences or paste characters directly:

{
  "customReplacements": {
    "[star]": "\u2605",
    "[heart]": "\u2764",
    "[arrow]": "\u279c",
    "[check]": "✔",
    "[cross]": "✘"
  }
}

Then in holograms:

/mh line set myHolo 1 1 &a[check] Task Complete
/mh line set myHolo 1 2 &c[cross] Task Failed