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,cloneor the API) live inconfig/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.bakkeeps the last real change (also across restarts). - When a hologram is deleted, its file and its
.bakare 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 reloadis 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 reloadfirst 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
.bakinstead, 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
.tmpwithout its main file is moved into place, and an incomplete one is removed (the.bakof that save is then restored if the main file is missing). - A
.bakwhose 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.jsonto 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.bakis 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"
]
}
}
]
}
locationisdimension:x:y:z. A hologram whose dimension is not loaded is skipped (with a warning) and stays on disk.update-intervalvalues below 1 are raised to 1 when the file is loaded.- Optional line fields:
offsetX,offsetZ,facing,scale,npcForcedLook,permission,flags. A missingheightuses the line type's default;0is a real height (the next line overlaps). Apermissionofnullmeans no permission, on a line as on the hologram. - Lectern hologram files also carry
owner,owner-uuidandlectern(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 underactions, 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 infoand/mh page infolist 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:
- 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. - The world writes
legacy-import.json, so it imports only once. - 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.