Repository navigation
Home
Companion can load any number of companion sets from your config folder. A set is a JSON file plus the images it references. Once installed, you can switch sets, resize the companion, change its animation speed, and place it in any corner of the screen.
Note
Always set the anchor relative to the corner the companion is placed.
- Open the
config/companion/folder (usually.minecraft/config/companion/). - Create a folder for your companion, for example
config/companion/my_companion/. - Add a JSON file and the images it references.
- Restart Minecraft.
- Open ModMenu → Companion and use the set switcher:
- Left-click: previous set
- Right-click: next set
- Adjust size, frametime, anchor, offset, visibility, and opacity, or use Move… to drag the companion into place.
| Format | Support | Notes |
|---|---|---|
| PNG | Static image | Standard transparency is supported. |
| GIF | Animated image | Frames are decoded and composited, including disposal handling. |
| JPG, WebP, APNG, etc. | Not supported | Only PNG and GIF files are loaded as of now. |
- Every entry in the
texturesarray is loaded in order. - A PNG contributes one frame.
- A GIF contributes all of its decoded frames at the position where it appears.
- All frames use the set's
frametime(milliseconds per frame). - Embedded GIF frame delays are currently ignored, so all frames play at the same speed.
- A single static PNG simply stays on screen.
- Width / height — resize the companion independently of the source image.
- Frametime — milliseconds per frame. used to control the animation speed.
-
Anchor —
top_left,top_right,bottom_left, orbottom_right. - Offset X / Y — move the companion away from its anchor.
- Visible — show or hide the companion.
- Opacity — 0–100%.
- Move… — drag the companion directly on screen.
Defaults when no config exists: 32×16 size, 1000 ms frametime, bottom_right anchor.
Editable ranges in the config screen: width/height 1–2048, frametime 1–10000 ms, offsets -4096–4096, opacity 0–100%.
-
config/companion/is scanned recursively for.jsonfiles. - Any file named
config.jsonis reserved and ignored. - A JSON file must contain a
texturesarray to be treated as a set. - Sets are sorted alphabetically by path.
- The selected set is saved in
config/companion/config.jsonand restored on the next launch. - If the saved set is missing, the first available set is used.
- The name shown in the switcher is the JSON filename without
.json; thenamefield is not used for this.
A set can recommend a width, height, and frametime. These appear as small suggested buttons next to the matching fields in the config screen. Click a button to apply that value. Suggested values are not applied automatically when switching sets.
config/companion/
└── my_companion/
├── my_companion.json
├── idle_0.png
├── idle_1.png
└── wave.gif
The JSON file can be at the root of config/companion/ or inside any subfolder. Image paths are resolved relative to the folder containing the JSON file.
{
"name": "My Companion",
"author": "Your Name",
"description": "A short description of the companion.",
"suggested": {
"width": 100,
"height": 100,
"frametime": 100
},
"textures": [
"idle_0",
"idle_1",
"wave.gif"
]
}| Field | Required | Type | Description |
|---|---|---|---|
textures |
Yes | Array of strings | Texture entries in playback order. Must be an array or the set is skipped. |
suggested |
No | Object | Recommended starting values shown as one-click buttons. |
suggested.width |
No | Positive integer | Suggested companion width. |
suggested.height |
No | Positive integer | Suggested companion height. |
suggested.frametime |
No | Positive integer | Suggested milliseconds per frame. |
name |
No | String | Metadata only. Currently not displayed in-game. |
author |
No | String | Metadata only. Currently not displayed in-game. |
description |
No | String | Metadata only. Currently not displayed in-game. |
Prefer the suggested object over the legacy top-level keys.
Entries are resolved relative to the JSON file's folder:
- The exact path as written, if it exists.
-
<name>.gif, if the entry had no extension. -
<name>.png, if the entry had no extension.
This means "cat_0", "cat_0.png", and "frames/cat_0" are all valid. File names are case-sensitive on most systems.
Entries are loaded in array order. If an entry cannot be found or fails to load, it is skipped and a warning is written to the log.
-
name,author, anddescriptionare reserved metadata and are not shown in-game yet. - GIF frame delays are ignored; the global
frametimecontrols playback. - Unsupported image formats are not converted automatically.
- New sets are discovered when the client starts, so restart Minecraft after adding or removing files.
- Invalid JSON, or a JSON file without a
texturesarray, is ignored.
Example sets live in public/companion:
| Set | Contents | Demonstrates | Suggested values |
|---|---|---|---|
cat |
cat.json, cat_0.png, cat_1.png
|
2-frame PNG loop | 100×100, 1000 ms |
cat_alt |
cat_alt.json, l0.png–l3.png
|
4-frame PNG loop | 32×16, 1000 ms |
hsr |
hsr.json, frame_0.png–frame_9.png
|
10-frame PNG loop | 100×100, 100 ms |
hsr2 |
hsr2.json, image.gif
|
Animated GIF | 100×100, 100 ms |
ilovecats |
ilovecats.json, ilovecats.png
|
Minimal single-image set | None |
To try one, copy its folder into config/companion/, restart the client, then select it from ModMenu → Companion.
-
The set does not appear in the switcher - Check that the JSON is valid, contains a
texturesarray, is not namedconfig.json, and that the client was restarted. -
Some frames are missing - Check the entry names and paths. Names are relative to the JSON folder and are case-sensitive; the
.png/.gifextension is optional. -
The animation speed is wrong -
frametimeis a single per-frame delay for the whole set. GIF-embedded delays are not used. -
The switcher shows the wrong name - The label comes from the JSON filename, not the
namefield. - Suggested values did nothing - Suggested values are applied only when you click their suggested buttons.