Configuration

Configuration Guide

There are two configuration layers: a global configuration that applies to every tooltip and a per-item/per-tag/per-namespace configuration for specific items.

---

1. Global Configuration

Path
config/tooltipoverhaul/tooltipoverhaul.toml

Usage
The global configuration changes all tooltips at once:

• Position of the second panel
• Change the icon background
• Enable/disable 3D item preview
• Text alignment and position
• Rotation speed of 3D items
• Inner border type: glint, gradient (default), static
• Etc.

Note: Keep in mind that the global configuration has lower priority than the specific configuration. If an item has a custom frame (as defined below), the configuration of that custom frame will take precedence over the global one. If a certain specific option is not defined, the global configuration will be applied instead.

---

2. Per-item / Per-tag / Per-namespace Configuration

This allows you to target specific items, tags or modids (namespaces) and customize their tooltip's appearance, using a file called custom_frames.json.

Path of custom_frames.json from Tooltip Overhaul
config/tooltipoverhaul/custom_frames.json

Path of custom_frames.json inside a resource pack or a mod per se
assets/<modid>/tooltipoverhaul/custom_frames.json

Replace <modid> with the modid you want. Personally, I recommend keeping things organized, since you can use any existing modid you want.

• If you're a modpack developer or a casual player, you can modify the custom_frames.json file inside the config/tooltipoverhaul folder, and add as much custom frames as you want, or you can either create a texture pack and add the custom_frames.json file under the path assets/<modid>/tooltipoverhaul, where <modid> is the mod of your choice, with as many custom frames as you want.
• If you're a mod developer, you can create that file under your own modid (for example, resources/assets/biomancy/tooltipoverhaul/custom_frames.json) and add custom frames to any of the items you want.

Any mod or texture pack can add compatibility without needing Tooltip Overhaul as a dependency.

Note: Only in this mod (Tooltip Overhaul), the custom_frames.json file has been moved from the internal assets folder to the config folder, so that anyone can modify specific frames without the need of creating a texture pack. If you're a mod developer, you must create the file inside your internal assets folder, as specified above.

---

3. JSON Structure

Note: JSON does not support comments. If you copy an example that contains // or /* */, remove them before using.

{
  // These are simulated comments, JSONs are purely data-driven files, so if you copy paste this file, you should
  // delete the comments too.
  //
  // author: xylonity
  //
  // This (custom_frames.json) file is the main file where you can configure custom tooltips, either via a
  // resource pack or a mod per se.
  //
  // This is a highly configurable mod, allowing the player to specify frames (animated or not), different
  // frame types, effects, and more. Below you'll find all possible configurations, whether for specific
  // items or for tags covering multiple items. For global configurations, edit the file at
  // config/bettertooltips.toml, since this JSON is only for specific decorations and won't affect all items
  // unless manually specified. Every configuration entry has a default value, so you don't need to list them all
  //
  "frames": [
    {
      // Texture path for the tooltip overlay.
      // Default: none (falls back to global frame overlay).
      "texture": "tooltipoverhaul:textures/overlay/default_frame.png",

      // Specific items that use this custom tooltip.
      "items": [
        "minecraft:netherite_sword",
        "minecraft:gray_wool",
        "minecraft:golden_apple"
      ],

      // Item tags that use this custom tooltip.
      "tags": [
        "minecraft:axes"
      ],

      // Namespace (modid) that this configuration applies to.
      // All items within the specified namespace will use this custom tooltip.
      // Use "*" or "all" to match every item.
      "namespace": "biomancy",

      // Text displayed under the item name (defaults to the item rarity).
      // Can be a literal string or a translatable key (e.g., "tooltipoverhaul.key.my_mod.my_item_rating").
      "itemRating": "Guacamole",

      // Text color for the itemRating.
      // Default: rarity color.
      "colorItemRating": "0xFFFFFF",

      // Alignment of the tooltip title (item name).
      // Options: "left", "middle", "right". Default: left.
      "titleAlignment": "left",

      // Alignment of the item rating (qualifier under the item name).
      // Options: "left", "middle", "right". Default: middle.
      "ratingAlignment": "middle",

      // Additional offset for the entire tooltip position (Horizontal/Vertical axes).
      "tooltipPositionX": 0,
      "tooltipPositionY": 0,

      // Horizontal and vertical padding for the main tooltip panel.
      "mainPanelPaddingX": 4,
      "mainPanelPaddingY": 2,

      // Background color of the tooltip (ARGB hex).
      "backgroundColor": "0xF0010110",

      // Rotation speed of the main item icon.
      "iconRotatingSpeed": 1.1,

      // Appearance animation of the main item icon.
      // Options: zoom, rotate, rotate_fast, rotate_zoom, zoom_snap, skew,
      // vibration, tilt_wave, flip, pendulum, bounce, go_down, pulse,
      // fan_in, hover_pop, barrel_roll.
      "iconAppearAnimation": "skew",

      // Additional offset for the secondary panel (Horizontal/Vertical axes).
      "secondPanelX": 0,
      "secondPanelY": 0,

      // Size of the secondary panel (Horizontal/Vertical axes).
      "secondPanelSizeX": 0,
      "secondPanelSizeY": 0,

      // Rotation speed of the 3D renderer in the secondary panel.
      "secondPanelRendererSpeed": 1.25,

      // Color of the divider line.
      // Options: "match_inner_frame_color", "match_item_name_color", or hex ARGB color (e.g., "0xA0EFEFEF").
      "dividerLineColor": "match_inner_frame_color",

      // Type of the divider line.
      // Options: gradient, static, linear.
      "dividerLineType": "gradient",

      // Top padding of the divider line (in pixels).
      "dividerLineTopPadding": 0,

      // Bottom padding of the divider line (in pixels).
      "dividerLineBottomPadding": 0,

      // Background style for the item icon.
      // Options: focus, void, slot, slot_border, glow.
      "iconBackgroundType": "slot_border",

      // Internal border type of the tooltip frame.
      // Options: glint, gradient, static, auto_glint, auto_gradient, auto_static.
      "borderType": "static",

      // Border gradient palette. Options: common, uncommon, rare, epic,
      // legendary, chaos, custom. Use "custom" to define your own colors.
      "gradientType": "custom",

      // Custom gradient colors (used if gradientType = "custom").
      // For "static", only the first color is used.
      "gradientColors": [
        "#555555",
        "#5bfe5b",
        "#1bab1b"
      ],

      // Special visual effect for the frame. 
      // Defaults to "none". Effects can be chained together.
      // Options: cinder, echo, galaxy, magic_orbs, speed_lines, nebula, spiral, white_dust, metal_shining, rim_light, ripples, sonar, stars.
      "specialEffect": "nebula, white_dust",

      // Vignette entries for gradient overlays around the tooltip background. Each vignette must be written in parentheses in this exact order:
      // "(type, position, color, radius, extraPositionX, extraPositionY)"
      // You can define multiple vignettes. 
      // type = vignette shape (options: circular, hole). position = anchor on the tooltip (middle, top_middle, bottom_middle, right, top_right, 
      // bottom_right, left, top_left, bottom_left). color = ARGB hex in #AARRGGBB. radius = relative size factor (e.g. radius 0.4). 
      // extraPositionX / extraPositionY = additional pixel offset from the chosen position.
      "vignettes": [
        "(circular, top_left, #FF567823, 0.4, 0, 0)",
        "(...)",
        ...
      ],

      // Whether to use the player's skin model in the secondary panel preview (for armor items).
      // Default: global config value.
      "usePlayerSkinInPreview": false,

      // Model to use in the preview panel.
      // Default: global config value.
      "previewPanelModel": "default",

      // Toggleable features:
      "showSecondPanel": true,        // Show or hide the secondary panel.
      "showRating": true,             // Show or hide the rating text.
      "showShadow": true,             // Show or hide the tooltip shadow.
      "disableIcon": false,           // Hide the main item icon.
      "disableScrolling": true,       // Disable tooltip scrolling.
      "disableDividerLine": true,     // Hide the divider line.
      "disableTooltip": false         // Disable this custom tooltip entirely.
    },
    {
      "texture": "...",
      "items": [
        "..."
      ],
      ...
    },
    {
      ...
    }
  ]
}

Configuration entries (quick reference)

• texture
• items
• tags
• namespace
• itemRating
• colorItemRating
• titleAlignment
• ratingAlignment
• tooltipPositionX
• tooltipPositionY
• mainPanelPaddingX
• mainPanelPaddingY
• backgroundColor
• iconRotatingSpeed
• iconAppearAnimation
• secondPanelX
• secondPanelY
• secondPanelSizeX
• secondPanelSizeY
• secondPanelRendererSpeed
• dividerLineColor
• dividerLineType
• dividerLineTopPadding
• dividerLineBottomPadding
• iconBackgroundType
• borderType
• gradientType
• gradientColors
• particles
• specialEffect
• vignettes
• usePlayerSkinInPreview
• previewPanelModel
• showSecondPanel
• showRating
• showShadow
• disableIcon
• disableScrolling
• disableDividerLine
• disableTooltip