Skip to content
Sutanu Krishna Majumder edited this page Nov 14, 2026 · 3 revisions

Custom companions

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.

Quick start

  1. Open the config/companion/ folder (usually .minecraft/config/companion/).
  2. Create a folder for your companion, for example config/companion/my_companion/.
  3. Add a JSON file and the images it references.
  4. Restart Minecraft.
  5. Open ModMenu → Companion and use the set switcher:
    • Left-click: previous set
    • Right-click: next set
  6. Adjust size, frametime, anchor, offset, visibility, and opacity, or use Move… to drag the companion into place.

Current capabilities

File formats

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.

Animation

  • Every entry in the textures array 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.

Customization

  • 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, or bottom_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%.

Companion sets

  • config/companion/ is scanned recursively for .json files.
  • Any file named config.json is reserved and ignored.
  • A JSON file must contain a textures array to be treated as a set.
  • Sets are sorted alphabetically by path.
  • The selected set is saved in config/companion/config.json and 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; the name field is not used for this.

Suggested values

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.

Companion JSON

Folder layout

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.

Example

{
  "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"
  ]
}

Fields

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.

Texture entries

Entries are resolved relative to the JSON file's folder:

  1. The exact path as written, if it exists.
  2. <name>.gif, if the entry had no extension.
  3. <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.

Current limitations

  • name, author, and description are reserved metadata and are not shown in-game yet.
  • GIF frame delays are ignored; the global frametime controls 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 textures array, is ignored.

Examples

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.

Troubleshooting

  • The set does not appear in the switcher - Check that the JSON is valid, contains a textures array, is not named config.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/.gif extension is optional.
  • The animation speed is wrong - frametime is 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 name field.
  • Suggested values did nothing - Suggested values are applied only when you click their suggested buttons.