Skip to content

Splicing Table Iota Rendering

Jump to bottom
[object Object] edited this page Nov 7, 2025 · 12 revisions

HexDebug includes a custom data-driven system for customizing how iotas are rendered in the Splicing Table, which is documented on this page.

File format

To set the renderer for an iota type {namespace}:{path}, a file must be added to a resource pack at assets/{namespace}/hexdebug_splicing_iotas/{path}.json. If this file does not exist, the fallback renderer will be used.

An iota renderer JSON file must, at a minimum, include a type or parent key. If both are present, type is always ignored and taken from the parent. The type field is a string containing the ID of a registered renderer (more on that later). The parent field is a string containing the ID of another iota type to inherit the renderer of (ie. "parent": "{namespace}:{path}" inherits from assets/{namespace}/hexdebug_splicing_iotas/{path}.json). Which fields are inherited depends on the implementation of the specific iota renderer in use.

All other fields in the file depend on the specific iota renderer being used.

Registering a custom renderer

A splicing table iota renderer consists of three parts: a parser, a provider, and a renderer. The parser (SplicingTableIotaRendererParser) is used to parse iota definition files with a type field matching that parser's ID, outputting a provider; the provider (SplicingTableIotaRendererProvider) is used to create renderers; and the renderer (SplicingTableIotaRenderer) is called when the renderer first becomes visible to create a tooltip, and each frame to get the background type and render the iota that it was created for.

Renderers may be created whenever the splicing table needs to change which iotas are visible. However, the GUI attempts to cache renderers when possible to improve performance; in this case, setX and setY may be called to move the renderer to a different slot in the table. If your renderer wraps other renderers, you should override setX and setY to also set the x and y position of the inner renderers.

To register a custom renderer, call the static method SplicingTableIotaRenderers#register in your mod's client initializer with an ID and an iota renderer parser. The ID should have your modid as the namespace, and may have any arbitrary path.

The method SplicingTableIotaRendererParser#parse is called for each JSON file that has your parser's ID in its type field, or the type field of its parent. This method is passed the raw JsonObject of the file, as well as the fully initialized parent object (if any). The parser is responsible for copying any missing values from the parent; HexDebug will not do this for you.

Built-in renderers

hexdebug:conditional/if_path_exists

Chooses between two renderers depending if a given NBT path exists in the iota's data tag.

Field Type Description Default
path string An NBT path to a value in the iota's data tag.
if string/object The ID of the renderer file, or a renderer definition, to use if the path exists.
else string/object The ID of the renderer file, or a renderer definition, to use if the path does not exist.
allow_in_sub_iota boolean If false, always use the else renderer when used inside of a renderer like hexdebug:sub_iota. This is false by default to prevent deeply nested iotas from rendering weirdly. false

Example:

{
  "type": "hexdebug:conditional/if_path_exists",
  "path": "[0]",
  "if": {
    "type": "hexdebug:layers",
    "layers": [
      {
        "renderer": "hexdebug:builtin/wide/list"
      },
      {
        "renderer": {
          "type": "hexdebug:sub_iota",
          "path": "[0]"
        },
        "scale": 0.75
      }
    ]
  },
  "else": "hexdebug:builtin/list"
}

hexdebug:item

Renders a scaled-down item stack. Uses the gold background type.

Field Type Description Default
item_path string An NBT path to an item ID in the iota's data tag.
block_path string An NBT path to a block ID in the iota's data tag. Only used if the tag referenced by itemPath is missing. null
count_path string An NBT path to a number in the iota's data tag representing the item stack count. The count defaults to 1 if not present. null
tag_path string An NBT path to a compound tag in the iota's data tag representing the item stack's NBT tag. null
x_offset float Horizontal distance to offset the item by when rendering over the button background. 0
y_offset float Horizontal distance to offset the item by when rendering over the button background. 0
scale float Scale multiplier to use when rendering the item. 0.75

Examples:

{
  "type": "hexdebug:item",
  "item_path": "item",
  "block_path": "block"
}
{
  "type": "hexdebug:item",
  "item_path": "moreiotas:stack_id",
  "count_path": "moreiotas:stack_count",
  "tag_path": "moreiotas:stack_tag"
}

hexdebug:layers

Renders multiple renderers in the same position. Allows scaling down each layer individually. Uses the background type of the first layer. Uses the tooltip of the last layer that has use_tooltip = true.

Field Type Description Default
layers list A list of RendererLayer objects.

RendererLayer:

Field Type Description Default
renderer string/object The ID of a renderer file, or a renderer definition.
scale float Scale multiplier to use when rendering this layer. 1.0
use_tooltip boolean If true and all subsequent layers are false, use this layer's tooltip for the iota. true

Example:

{
  "type": "hexdebug:layers",
  "layers": [
    {
      "renderer": {
        "parent": "hexdebug:builtin/wide/type",
        "use_iota_color": false
      }
    },
    {
      "renderer": {
        "type": "hexdebug:item",
        "item_path": "item",
        "block_path": "block"
      },
      "scale": 0.75
    }
  ]
}

hexdebug:list

Expects an iota with a ListTag as its data value, and adds an advanced tooltip with the list's length. Uses the provided renderer for all other rendering purposes.

Field Type Description Default
renderer string/object The ID of a renderer file, or a renderer definition.

Example:

{
  "type": "hexdebug:list",
  "renderer": "hexdebug:builtin/list"
}

hexdebug:pattern

Renders a pattern iota using Hex Casting's built-in renderer. Uses the slate background type. Expects an iota with a serialized HexPattern as its data value, and adds an advanced tooltip with the pattern's angle signature.

Example:

{
  "type": "hexdebug:pattern"
}

hexdebug:sub_iota

Renders an iota stored inside of this iota's data tag.

Field Type Description Default
path string An NBT path to an iota in the iota's data tag. 
{
  "type": "hexdebug:sub_iota",
  "path": "[0]"
}

hexdebug:texture

Renders an arbitrary texture from a resource pack. Uses the gold background type.

Field Type Description Default
texture string Path to the texture file to use. Example: hexdebug:textures/gui/splicing_table.png
x_offset int Horizontal distance to offset the texture by when rendering over the button background. 0
y_offset int Vertical distance to offset the texture by when rendering over the button background. 0
u_offset int Horizontal position of the texture in the given file. 0
v_offset int Vertical position of the texture in the given file. 0
width int Width of the texture to render. 18
height int Height of the texture to render. 21
texture_width int Total width of the given file. 18
texture_height int Total height of the given file. 21
use_iota_color boolean If true, tint the rendered texture using the color() method of the iota's type. true

Examples:

{
  "type": "hexdebug:texture",
  "texture": "hexdebug:textures/gui/splicing_table.png",
  "x_offset": 2,
  "y_offset": 3,
  "u_offset": 337,
  "v_offset": 73,
  "width": 14,
  "height": 14,
  "texture_width": 512,
  "texture_height": 512,
  "use_iota_color": true
}
{
  "parent": "hexdebug:builtin/base",
  "u_offset": 337,
  "v_offset": 73
}

Built-in icons

HexDebug includes several built-in icons, based on the hexdebug:texture renderer, that you can use as-is for your own iotas if you wish. To use any of these, your iota definition file should look like this:

{
  "parent": "hexdebug:builtin/{name}"
}

For example:

{
  "parent": "hexdebug:builtin/type"
}

The full list of built-in icons is as follows:

  • hexdebug:builtin/boolean
  • hexdebug:builtin/continuation
  • hexdebug:builtin/double
  • hexdebug:builtin/entity
  • hexdebug:builtin/garbage
  • hexdebug:builtin/generic
  • hexdebug:builtin/list
  • hexdebug:builtin/matrix
  • hexdebug:builtin/null
  • hexdebug:builtin/string
  • hexdebug:builtin/type
  • hexdebug:builtin/vec3
  • hexdebug:builtin/wide/list
  • hexdebug:builtin/wide/type

Clone this wiki locally