The tooltips layouts used by an item or object are defined by a Tooltip Kind.

There are 2 configs each tooltip kind uses:

• .itemdescription (located in /interface/itemdescriptions), used in crafting;
  
• .tooltip (located in /interface/tooltips), used when hovering over the item.

These files are UI configs called Pane Layouts - check out the link in Learn More to know more about them.

Pane layouts consits of Widgets - JSON objects describing a visual element, like a label (text object) or an image.

Checkout vanilla tooltip configs for examples.

The logic of how these tooltips interact with items is a bit hardcoded, but there are parts of it that you can control, and are described later in the guide.

What you'll need to do is to create the 2 config files described in above section for your item in the relative folders in your mod folder.

You can use vanilla base.itemdescription and base.tooltip as a base to go off of.

Let's say your tooltip kind will be called myTooltipKind. You'll have:

• myMod/interface/itemdescriptions/myTooltipKind.itemdescription
  
• myMod/interface/tooltips/myTooltipKind.tooltip
  

Both of the files you've created (.itemdescription & .tooltip) will have a similar structure - they are both sets of Pane Layout Widgets. Both will have similar widgets defined in them, but with different positioning, font sizes, etc.

Most of what you will need are the widgets with "type" : "label" parameters, since these are responsible for the text displayed in the tooltips.

The background images can be set via the "background" widgets:

For other widgets, you'll want to know their "position", which is calculated from the bottom-left of the entire widget (so account for footer, not just the body).

For text widgets - if they are meant to be hardcoded, set the text in "value". If not - leave them blank (""), and see the following sections of the guide to know how to fill them in.

Other useful text widget parameters are "lineSpacing" (default is 1.2 I think), "fontSize" (default is 8?..) and "wrapWidth" (default is unlimited I guess, but note that your text will get cut off if it will escape the tooltip boundaries).

Note that you can check the full list of possible widget parameters via the link in the Learn More section of this quide.

You might notice that some items have "tooltipKind" : "something-something" - this is the part you need.

Add it to your item of object file like this:

If you're setting it via a lua buildscript, then something like this:
Note that this is an overwriteable value, so will be overwritten if set via parameters.

If you're modifying an existing object or item wia a .patch file, this is how it will look for you:

• if that item/object doesn't have a tooltip kind explicitly specified already:
  
  { "op" : "add", "path" : "/tooltipKind", "value" : "myTooltipKind" }
• if that item/object already has a "tooltipKind" specified:
  
  { "op" : "replace", "path" : "/tooltipKind", "value" : "myTooltipKind" }

When adding a new tooltip, you will probably want to have custom values displayed on it that are usually not displayed in vanilla tooltips, like item/object level or species.

You'll see that some value connections are "hardcoded" - they work without you having to say so explicitly in item's config or buildscript - things like descriptionLabel, priceLabel, etc.

Thankfully, you can add custom values to the tooltip an populate them from item config!

The only 2 limits are:

• it has to either be a text value or a root-relative image path;
  
• the widget you're setting the value for has to be a top-level label or image.

This means that:

• you can't set stuff like font size this way (through item), only by setting it in the tooltip config;
  
• no nested fields or populated lists life the hardcoded effect list in armor tooltips.

This can be done in one of 2 ways:

1. By setting the values in the item config file itself:
   create a tooltipFields dict in the item config:
   
   "tooltipFields" : { }
   now add your values there in format "widgetName" : "value":
   
   "tooltipFields" : { "myCoolLabel" : "This item is awesome!", "myCoolImage" : "/objects/funny/funny.icon" }
2. If you want to set these values dynamically, you can do that in a buildscript. Checkout vanilla buildscripts in /items/buildscripts for examples!

Here are other guides/questions I was able to find on this matter, hopefully they will help you too!

Here you can find all the parameters of all the widget types you might use in your tooltip configs:
https://starbounder.org/Modding:JSON/Variables/Panes_(GUI)

...like forgetting to set a "tooltipKind" value.
https://community.playstarbound.com/threads/solved-custom-tooltip-layout-for-custom-consumables.142781/
https://www.reddit.com/r/starbound/comments/6aha41/can_you_show_tooltip_for_custom_weapon_i_tried/

For some more complicated examples of tooltip configs and usage of lua buildscripts to populate them, check out custom tooltips from some of these mods:
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=2006558650
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=731354142
https://steamhost.cn/steamcommunity_com/sharedfiles/filedetails/?id=1827029602
Feel free to ask questions in the comments as well and thank you for reading this!