Basic Terminology & Structure

Basic Objects

The first thing that will be found in almost all GUIs will be the “namespace”, this is at the top of the file.

“namespace”: “…”

This is used when you are accessing objects from separate files.

Anything else inside the file will be an object which can have any name as long as there isn’t two objects with the same name in one file.

“(name)”: { … }

Special Symbols

There are a few special symbols that are used in object names to mean certain things, or used in certain conventions.

@ – Used for parenting
Parenting is a way to create an object that inherits all the values contained within the parent object, you can create a placeholder object that will have values input into it, it can also be used to create the same object, but replacing specific values within.


Where (parent) is the (name) of another object.

. – Used for calling an object from another namespace
You can use objects from another file and namespace, either within an object or as a parent object.


“name”: {
“value”: “(namespace).(parent)”

If you call an object from another namespace you must supply the namespace, if the object is within the same namespace the namespace is not necessary in all situations.

$ – Used for variables or placeholders
When creating values inside an object you can use variables instead of other objects, this allows you to parent an object, which controls several objects, you can then use variables inside and change the variable over different child objects.

“my_object”: {
“$texture|default”: “def_image”,
“controls”: [
{ “img@$image”: {} },

“image_view_1@my_object”: {
“$texture”: “image_1”

“image_view_2@my_object”: {
“$texture”: “image_2”

In the example both “image_view_1” and “image_view_2” will be the same but with different images. By doing it this way you don’t have to redefine all the objects that the object controls.
The use of “|default” after the variable name allows a default value to be specified, if the object is used as a parent without defining “$texture” the default value will be used instead.

# – Used for bindings and other special items
Bindings are special values that are harcoded into Minecraft, they are used in certain situations, ‘#’ is also used for special values, again hardcoded into Minecraft. You can’t create new bindings.

Common Object Types

When defining objects they will need to have a type defined, either inside the object or via the object’s parent.

“name”: {
“type”: “(type)”

Panel – An extremely common object type will be a panel, this is an object that contains within itself several other objects, ready to be display in-game.

“name”: {
“type”: “panel”,
“size”: [width, height],
“controls”: [


The “controls” value within a panel will contain several defined objects, which will be displayed with the panel in-game, images, buttons, text …

Image – All textures used in GUIs must be from a defined “image” object, with a texture and often a size given, which will be the size of the image in-game, in pixels.

“name”: {
“type”: “image”,
“size”: [width, height],
“texture”: “path/to/texture”

The path given will start from the main resourcepack folder ie “textures/ui/my_image”.

Label – A label is simply text, often seen in the top left of containers, “chest”, “inventory”, “dispenser”…

“name”: {
“text”: “Words go here”,
“color”: [0.4, 0.95, 0]

The text of a label is the words that will appear, this is a tranlated string, meaning if you input text that appears in a lang file ie “”, the text will be translated by the language the user has selected.
The color of the text is an rgb list with the values being decimals between 0 – 1, ie [1, 0, 0] would be pure red.

There are many different types of objects that are encountered within data driven GUIs but I won’t go into all of them now.

Texture Nine-Slicing

Some GUI textures will have an accompanying json file, it will be named the same as the texture name.
Not all textures will use this, but the reason for using this json file is to enable nine-slicing when the image is resized in-game.

There will be two values inside the json file, firstly is “base_size”:

“base_size”: [width, height]

This is simply the size of the texture that the json file corresponds to.

Next is “nineslice_size”.

What is nine-slicing?

Nine-slicing is the act of marking an image into nine sections which will be used when resizing the image.

The (rather plain) image on the right has been split into 9 sections using nine-slicing.


What happens when an image with nine-slicing is resized is simple:nine_slice_resize
The 4 corners remain the exact same size.
The top and bottom middle sections will be resized horizontally.
The 2 side middle sections will only be resized vertically.
Also the middle section will be resized both horizontally and vertically.
This is demonstrated in the image on the right.

Setting the Nine-Slice Sizes

nine_slice_xyInside the json file for the texture you can specify the “nineslice_size”, but there is 3 different ways to do this, used in varying situations.

One value:
Supplying a single value will set X1, Y1, X2, and Y2 to this single value.

Two value array:
You can provide two nine-slice values via an array, what this will achieve is to give X1, X2, the first number and Y1, Y2, will be the second number in the array.

Four value array:
Providing 4 number in an array will unsurprisingly map each number to an individual number, allowing very specific control. The numbers need to be supplied in the order X1, Y1, X2, Y2.

All values supplied will be given in pixels, where 1 will mean there is a single pixel in each corner, 2 the corners will be a 2×2 square of pixels etc …

“nineslice_size”: 3

“nineslice_size”: [3, 5]

“nineslice_size”: [3, 5, 3, 1]

< Go back to see more specific tutorials