Skip to content

Storage & Backups

MasuHolograms keeps everything in JSON files. This page lists where each file lives, how saves protect them, and the format of a hologram file.

File Locations

config/masuholograms/
├── config.json                 # Main configuration
├── lang.json                   # Player-facing messages
├── animations/                 # Animation JSON files
│   ├── typewriter.json
│   ├── wave.json
│   ├── burn.json
│   ├── scroll.json
│   ├── colors.json
│   └── example_frames.json
└── holograms/                  # Admin holograms, shared by every world
    └── my_hologram.json

<world>/masuholograms/          # Per world (e.g. world/masuholograms/)
├── lectern-tracker.json        # Which lectern holds which lectern hologram
├── legacy-import.json          # Marker: pre-1.3.0 lecterns imported
└── players/
    └── <owner uuid>/
        └── lectern_Steve_100_65_200.json
  • Admin holograms (made with /mh hologram create, clone or the API) live in config/masuholograms/holograms/, one file per hologram named after it. They are global: they survive a world reset and, in singleplayer, show up in every world (in the dimension and at the position they were made).
  • Lectern holograms (made by players with a Hologram Book) and the lectern tracker live in the world folder, so a new or reset world starts without them and a lectern check never touches the holograms of another world.

Saving

  • Commands save the hologram they change at once. Changes made through the API with markDirty() are written within a second.
  • Every write goes to a temporary file (.tmp) first, which is then moved into place, so a crash or power loss mid-write never leaves a half-written file.
  • Before a file is replaced, the previous version is kept next to it as <name>.json.bak. A save that would write exactly what the file already holds is skipped, so the .bak keeps the last real change (also across restarts).
  • When a hologram is deleted, its file and its .bak are removed. Deleting and renaming are written to disk at once.
  • A save that keeps failing (disk full, no write permission) is logged once and retried; the log says when the file is written again. /mh reload is refused while a hologram is unsaved, so the older file on disk cannot replace it.
  • On a server stop, every hologram is saved and the mod waits for the writes to finish.
  • /mh reload first writes pending changes; if they cannot be written in time, the reload is aborted and nothing changes (see the server log).

Recovery at Startup

  • A file that cannot be read is loaded from its .bak instead, with a warning in the log. If both are unreadable, the hologram is skipped and the error is logged; the files stay untouched.
  • A save that was interrupted is finished: a complete leftover .tmp without its main file is moved into place, and an incomplete one is removed (the .bak of that save is then restored if the main file is missing).
  • A .bak whose main file is gone without any trace of an interrupted save means the file was deleted by hand: it is left alone and the log names it. Rename it to .json to bring that hologram back; delete it to be rid of it.
  • An unreadable lectern tracker is kept as lectern-tracker.json.corrupt-<time> (never overwritten) and its .bak is used. Lectern holograms without a tracker entry get one again from their own files.

Editing Files by Hand

You can edit hologram files and run /mh reload, but commands are safer. A hologram changed in game during the last second is written first and wins over your edit; to be sure, make no changes in game between editing the file and reloading. A file with a syntax error is skipped (or loaded from its .bak) and the error is logged.

The name field inside the file is the hologram's name; the file name does not matter. Files in subfolders of holograms/ are loaded too, except holograms/players/ (see below), so you can sort your holograms into folders. A hologram is saved back to the file it was loaded from; a renamed hologram, and one made in game, gets holograms/<name>.json.

Two files must not hold the same name (names ignore case). If they do, only one is loaded: <name>.json when it is one of them, otherwise the first by path. The log names both files, and the other one is not loaded and never changed.

Hologram File Format

{
  "name": "example",
  "location": "minecraft:overworld:0.5:65.0:0.5",
  "enabled": true,
  "permission": null,
  "display-range": 48,
  "update-range": 48,
  "update-interval": 20,
  "facing": 0.0,
  "down-origin": false,
  "flags": [],
  "pages": [
    {
      "lines": [
        {
          "content": "&bHello, {player}!",
          "height": 0.3
        },
        {
          "content": "#ICON:DIAMOND",
          "height": 0.6,
          "offsetX": 0.5,
          "permission": "vip.access",
          "flags": ["DISABLE_PLACEHOLDERS"]
        }
      ],
      "actions": {
        "RIGHT": [
          "MESSAGE:&aYou clicked!",
          "SOUND:minecraft:entity.experience_orb.pickup:1.0:1.0"
        ],
        "SHIFT_RIGHT": [
          "NEXT_PAGE"
        ]
      }
    }
  ]
}
  • location is dimension:x:y:z. A hologram whose dimension is not loaded is skipped (with a warning) and stays on disk.
  • update-interval values below 1 are raised to 1 when the file is loaded.
  • Optional line fields: offsetX, offsetZ, facing, scale, npcForcedLook, permission, flags. A missing height uses the line type's default; 0 is a real height (the next line overlaps). A permission of null means no permission, on a line as on the hologram.
  • Lectern hologram files also carry owner, owner-uuid and lectern (the lectern position).
  • Flag names and click types are matched exactly (upper case). A name this version does not know, in flags (hologram or line) or as a key under actions, is kept and written back on every save (an unknown click type with its whole value; known names come first and a repeated name is written once); it does nothing. The server log names them once per hologram when it loads (with a hint such as "did you mean RIGHT?" for a name that only differs in case or spaces), and /mh hologram info, /mh line info and /mh page info list them. Fix a typo in the file and run /mh reload.

Upgrading from Before 1.3.0

Before 1.3.0, lectern holograms were stored globally in config/masuholograms/holograms/players/<player name>/ with config/masuholograms/lectern-tracker.json. On the first start of each world with 1.3.0:

  1. The old lectern holograms are copied into that world's <world>/masuholograms/ (their text is cleaned with the current book rules). A copy never overwrites a file the world already has.
  2. The world writes legacy-import.json, so it imports only once.
  3. The old files are renamed to .migrated; nothing is deleted.

An imported hologram whose owner cannot be found (no tracker entry and no name in the server's usercache.json) goes to players/unknown-owner/. Imported holograms do not count towards their owner's limit until the lectern check has found their lectern. They are checked against their lecterns like any other: one whose lectern (with its Hologram Book) is not there is removed as soon as the lectern check sees that spot loaded. Old files that appear after a world's import are only renamed; delete legacy-import.json and restart to import them.

If you reset your world and do not want the old lectern holograms back, delete config/masuholograms/holograms/players/ and config/masuholograms/lectern-tracker.json (and their .bak / .migrated copies) before the first start.