Modding:JSON/Variables/Panes (GUI)

From Starbounder - Starbound Wiki
Jump to: navigation, search
Mining Hazard Sign.png
Work In Progress!
Mining Hazard Sign.png

This article or section is currently in the process of an expansion or major restructuring.
You are welcome to assist in its construction by editing it as well.

Last edited by PAThiCcSTaR on 2024-01-03 04:50:21.

Interface descriptions are also stored in JSON, found in the assets/interface folder. Note that some of those are hardcoded (namely assets/interface/windowconfig) - you can modify parameters at your own risk but adding more scripts/callbacks to those is impossible.

Interfaces can be of several types, including CraftingPanes, ContainerPanes (ContainerPane Lua functions) and ScriptPanes (ScriptPane Lua functions). The "pane" is basically a in-game window, usually consisting of a background and some window elements (widgets - Widget Lua functions). Their syntax is more or less the same.

In-window coordinates are always counted from down-left corner (zero). Window size is limited by its background (if the header and footer are present, they are considered part of the background).

All widgets

These parameters are the same for all widgets (with few exceptions).

Parameter Name Mandatory Variable Type Description
type yes string Type of the widget dependent on this. See below.
position yes Vec2F Position in pixels [x, y]. Counted from down-left corner (header+background+footer).

Background doesn't have it.

zlevel no int Layer. The window is drawn from negative layers to positive. Widgets with higher zlevel will overlap the rest.

Default: 0.

disabled no bool Defines if a widget can be used (for active widgets with callbacks). Disabled buttons are grayed out.

Default: false.

data no string Data readable via widget.getData() and writable via widget.setData(). Default: nil.
visible no bool Defines if a widget is visible. Default: true.
mouseTransparent no bool Determines if the gui will ignore this widget when toggling mouseover effects. Useful on labels and images that are displayed over interactive widgets such as buttons and radio groups. Default: false.

Background

Background is the base of your pane. Window size depends on it. Note that background doesn't have position parameter as it always occupies the whole window. It, however, can be semi-transparent or have transparent parts. Background is rendered in the following order: header, body, footer. It's best to declare it at the top of your interface.

Parameter Name Mandatory Variable Type Description
type yes string Always background. Required
fileHeader no string Header image path. Must be absolute.
fileBody yes string Body image path. Must be absolute.
fileFooter no string Footer image path. Must be absolute.

LabelWidget

A simple text label.

Parameter Name Mandatory Variable Type Description
type yes string Always label. Required
value yes string Label text. Can be an empty string or include \n to start a new line.
hAnchor no string left, mid or right. Horizontal text alignment.
vAnchor no string top, mid or bottom. Vertical text alignment.
color no string Text color in HTML format #NNNNNN, color name (for named colors) or Vec3I ([R, G, B]). White by default.

You can also apply color in the value itself (or to the part of the value) as a pre-directive, format ^#NNNNNN;text. The text before the directive will use color if it is available.

wrapWidth no int Max label width in pixels. If label text is bigger than that, it will be "wrapped" using "line feed", automatically making two-line etc labels as required. The game first tries breaking the text on spaces. If the resulting substrings still don't fit into target width they are further broken between characters.

Useful when using LabelWidget inside ScrollAreaWidget.

fontSize no float Size usually increases/decreases in 0.3 increments.

Example

"ra_lblTemplate" : {
	"type" : "label",
	"position" : [207, 189],
	"hAnchor" : "mid",
	"value" : "Template"
}

TitleWidget

Title widgets are usually present in crafting stations. They display information about the object, some text and a unique icon of the crafting station. SBModdingTitleWidgetExample.png

Parameter Name Mandatory Variable Type Description
type yes String Always title. Required.
title no String The upper text of the title, shown in white text. Usually may be replaced by the object that uses the pane with this widget with the value /interactData/paneLayoutOverride.
subtitle no String The lower text of the title, shown in grey text. Usually may be replaced by the object that uses the pane with this widget with the value /interactData/paneLayoutOverride.
icon yes Object(or dictionary) This parameter contains the same key-value pairs as an ImageWidget(you'll find it below). The position offset is calculated starting from the position of this (parent) widget.

ButtonWidget

Buttons can have "pressed" images, using them when, well, pressed, or pressedOffset, imitating button shifting when pressed.

Parameter Name Mandatory Variable Type Description
type yes string Always button. Required
base string Button image path when idle.
hover string Button image path on hover.
pressed string Button image path when pressed.
disabledImage string Button image path when disabled.
pressedOffset no Vec2F Button moves [x,y] inside the window when pressed.
caption no string Text on the button.
fontColor no Color of the caption.
fontColorDisabled no Color of the caption when the button is disabled.
textAlign no "left", "center" or "right". Caption alignment.
textOffset no Vec2I Caption offset (based on align).
callback no string Name of the function called on click. Defaults to button's name.

CheckBoxWidget

Any button can be made into a checkbox. A checkbox is essentially a button that can be toggled on/off. In addition to standart button properties, it has these:

Parameter Name Mandatory Variable Type Description
checkable yes bool Always true. Required. This is what makes a button a checkbox.
checked bool Checkbox state.
baseImageChecked string Checkbox image path when toggled on.
hoverImageChecked string Checkbox image path when toggled on and on hover.
pressedImageChecked string Checkbox image path when toggled on and pressed.
disabledImageChecked string Checkbox image path when toggled on and disabled.

TextBoxWidget

This widget's functions are what you would expect from your usual textbox. It is used for user text input - with some nuances.

Parameter Name Mandatory Variable Type Description
type yes string Always textbox. Required
regex no string If present, it limits characters input by regular expression. For example, a textbox with regex of "[a-zA-Z0-9 ]{0,30}" allows a text of 30 characters limited to English lowercase and uppercase letters, digits and a [Space] symbol. You can use online regex parsers like https://regex101.com/ to test your expression.
maxWidth no int Maximal visible width of the textbox in pixels. Defines the amount of text visible to user. The user can still navigate the string using the keyboard cursor buttons even if the text does not "fit" into the textbox.
focus no bool Defines if the user is "focused" on the textbox. Focus being "true" means the input cursor inside the textbox is active, and keyboard input will result in new text.
escapeKey no string Function which is called when a player hits [Esc] while being in a textbox with focus = true. (Pressing [Esc} with focus = false usually results in current in-game window being closed)
enterKey no string Function which is called when a player hits [Esc]/[Enter] while being in a textbox. Focus is not required.
callback no string Function called on left click on the textbox. Unlike the above callbacks, this callback will fire every time the user presses any key while the textbox is in focus. It will also fire once when focus is lost.
hint no string Hint for input which is shown in grey letters when the textbox does not contain user text.

ImageWidget

You may want to use Image post-processing directives

Parameter Name Mandatory Variable Type Description
type yes string Always image. Required
file string Image path.
centered no bool
trim no bool
minSize no Vec2I
maxSize no Vec2I
scale no integer

CanvasWidget

Not necessarily a "functional" widget in the sense that this widget needs to be outside of the "gui" table to function correctly. For more information, take a look at the easel, fossil tool, and Mazebound64 ScriptCanvas's.

Parameter Name Mandatory Variable Type Description
type yes string Always canvas. Required
rect yes Vec4I Bounding rectangle, [xmin, ymin, xmax, ymax].
captureMouseEvents bool Callback name for mouse handler
captureKeyEvents bool Callback name for keyboard handler

ItemGridWidget

A grid of slots for putting items in. Typically can be seen in containers or different kinds.

Parameter Name Mandatory Variable Type Description
type yes string Always itemgrid. Required.
dimensions yes Vec2I "Size" of the itemgrid in slots, [x,y]. An itemgrid of [2, 3] will have 2 columns of 3 slots each.
spacing yes Vec2I The amount of space between item slots. A value of [20, 20] will result in 20 pixels horizontally and 20 pixels vertically.
slotOffset no int If you have 2 itemgrids or more, you can set an offset for 2nd itemgrid here to prevent itemgrids from "overlapping". Example: if you have 2 slots in itemGrid and 4 slots in itemGrid2, you can set slotOffset for itemGrid2 to 2 (its slots' numeration will thus skip 1-2 and proceed with 3-6).
backingImage no string Path to background image for each slot.
callback no string Name of the function called on left click. Warning! If you add this property, putting items with left click will be impossible (callback replaces default slot functionality).
rightClickCallback no string Name of the function called on right click. Warning! If you add this property, putting items with right click will be impossible (callback replaces default slot functionality).

Note: adding both callback and rightClickCallback makes the itemgrid impossible to use normally (you won't be able to put/pick items manually).

ItemSlotWidget

Tt can be used as a quick way to mimic a container slot via the use of "widget.setItemSlotItem" and its related functions. Unlike an item grid, this will function regardless of whether the pane is linked to a container object or not.

If an item has been provided via script, its item descriptor will appear on MouseOver.

trying to place items into the ItemSlot will only call the widget's callback.

That being said, you can mimic container functionality by utilizing both the ItemSlotItems widget functions and:

player.swapSlotItem() player.setSwapSlotItem(Json item)

(both of which can be called from a pane script)


Parameter Name Mandatory Variable Type Description
type yes string Always itemslot. Required
position yes Vec2I [x, y].
backingImage yes String Absolute image path to an image file. This parameter works in the same manner as the one used in a button widget.
callback yes String Callback when left-clicking the itemSlot. The widgetName is passed as a argument.
rightClickCallback yes String Callback when right-clicking the itemSlot. The widgetName is passed to the callback function as an argument.
showBackingImageWhenEmpty no Boolean Unknown.
showBackingImageWhenFull no Boolean Not sure if this is used either, again, may be an internal thing.
showRarity no Boolean Unknown.
showDurability no Boolean Unknown.
showCount no Boolean Unknown.

RadioGroupWidget

A grouped collection of selectable buttons. At most, only one button can be selected at the same time.

GUI-RadioGroupWidget.png
Parameter Name Mandatory Variable Type Description
type yes string Always radioGroup. Required
toggleMode no boolean Value indicating whether the selected button can be deselected by clicking on it again. Defaults to false.
callback no string The name of the function to call when a button has been (de)selected. The same function should be defined in the scriptWidgetCallbacks array. Default to the name of the widget.
buttons yes array Collection of buttons that belong in the radio group. The parameters of each button are described below. Required

Button parameters:

Parameter Name Mandatory Variable Type Description
id no int While not mandatory, setting the id with the index position of the button array (base 0) will change the radiogroup widget's behavior.

Callback functions will pass in this argument, along with the radioGroup name. You will be able to access each button widget directly via a json path. See example for more information.

baseImage yes string Button image path when not selected. Not required, but the button is invisible unless a value is set.
hoverImage no string Button image path when not selected and hovered over.
baseImageChecked no string Button image path when selected.
hoverImageChecked no string Button image path when selected and hovered over.
pressedOffset no Vec2F Offset to the default position while the button is pressed. If no baseImageChecked is set this offset persists until the button is deselected. Defaults to [1,-1].
position no Vec2F Position of the button relative to the radio group. Defaults to [0, 0].
selected no boolean Value indicating whether this button is selected by default. If multiple buttons have this value set true, no button will be selected. Defaults to false.
visible no boolean Value indicating whether this button is visible. Defaults to true.

Example

"sampleRadioGroup" : {
  "type": "radioGroup",
  "toggleMode": true,
  "callback": "radioGroupCallback",
  "position": [
    100,
    100
  ],
  "zlevel": 1,
  "buttons": [
    {
      "id" : 0,
      "baseImage": "/interface/crafting/items.png",
      "hoverImage": "/interface/crafting/items.png?brightness=30",
      "baseImageChecked": "/interface/crafting/itemsSelected.png",
      "hoverImageChecked": "/interface/crafting/itemsSelected.png?brightness=30",
      "pressedOffset": [ 0, -1 ],
      "selected": true
    },
    {
      "id" : 1,
      "baseImage": "/interface/crafting/main.png",
      "hoverImage": "/interface/crafting/main.png?brightness=30",
      "baseImageChecked": "/interface/crafting/mainSelected.png",
      "hoverImageChecked": "/interface/crafting/mainSelected.png?brightness=30",
      "pressedOffset": [ 0, -1 ],
      "position": [ 19, 0 ]
    }
  ]
}

Notes

Button styling/captioning

RadioGroupWidget buttons, with defined ids, are viewed as ButtonWidgets. While the RadioGroupWidget logic unfortunately ignores JSON parameters not listed above, some (most? all?) of the Lua functions (under the widget table) that modify the visuals of ButtonWidgets will work on a button in a RadioGroupWidget. Access each button by using its JSON path: "<'string' radiogroupWidgetName>.<'string' id>".

Using the example config above, this Lua function will change the overlay image of both buttons in "sampleRadioGroup":

function changeButtonImages()
 widget.setButtonOverlayImage("sampleRadioGroup.0", "/images/image.png")
 widget.setButtonOverlayImage("sampleRadioGroup.1", "/images/image2.png")
end

Likewise, if you want to set captions:

function changeButtonTexts()
  widget.setText("sampleRadioGroup.0", "Foo")
  widget.setText("sampleRadioGroup.1", "Bar")
end

Setting the selected option

Widget.setSelectedOption("sampleRadioGroup", 0) selects the button with "id": 0 as one would expect. Contrary to any previous advice on this wiki page, do not use -1 or some other value not present in the button list; doing so will result in crashes.

Callback parameters

Despite "id": 0 (etc.) being an integer in the JSON data, the radio group callback receives a string, not a number/integer. Therefore, instead of the following:

function radioButtonCallback(id)
  if id == 0 then doSomething() end
  if id == 1 then doSomethingElse() end
end

You should write:

function radioButtonCallback(id)
  if id == "0" then doSomething() end
  if id == "1" then doSomethingElse() end
end

ScrollAreaWidget

An empty widget of a predefined size with a scroll bar to the right side. If content exceeds the height of the widget the scroll bar becomes active, allowing you to scroll up and down. The scroll area is limited to having a vertical scroll bar; a horizontal scroll bar can not be added.

The scroll area will automatically adjust the positions of all widgets to leave as little padding as possible. This means increasing the vertical position of all your widgets by 100 does not result in any changes.

To reference any ScrollArea children widgets in Lua scripts (widget.* table) use the following format: <ScrollArea name>.<Children widget name>.

GUI-ScrollAreaWidget.png
Parameter Name Mandatory Variable Type Description
type yes string Always scrollArea. Required
rect no Vec4F Array of four numbers, indicating the bottom, left, top and right bound of the scroll area. Not required, but the scroll area won't show up if no value is set. Use either this parameter, or "position" & "size" parameters below
position no Vec2F Array of two numbers indicating the starting position of the ScrollArea widget. This position will end up being the bottom-left corner of your ScrollArea.
size no Vec2F Array of two numbers indicating the width and height of the ScrollArea widget.
buttons no table You can use this custom table to override default buttons. See below.
thumbs no table You can use this custom table to override default thumbs (scrollers). See below.
children no table Table of widgets. Not required, but not having any widgets renders the scroll area useless.

Syntax for buttons override table for ScrollArea. If you override default buttons with this table ALL buttons are mandatory (even the unused horizontal ones), otherwise your pane will throw a (JsonException) No such key in Json exception. Seems like reading all the buttons is hardcoded in the game.

Parameter Name Mandatory Variable Type Description
horizontal yes table Includes overrides for "forward" and "backward" buttons. Required
horizontal/forward yes table A table similar to that of a ButtonWidget. base, hover and pressed parameters are mandatory (the paths can be empty strings).
horizontal/backward yes table
vertical yes table Includes overrides for "forward" and "backward" buttons. Required
vertical/forward yes table
vertical/backward yes table

Syntax for thumbs (scrollers) override table for ScrollArea. If you override default thumbs with this table ALL parameters are mandatory (even the unused horizontal ones), otherwise your pane will throw a (JsonException) No such key in Json exception.

Parameter Name Mandatory Variable Type Description
horizontal yes table Includes overrides for the unused horizontal scroller. Required
horizontal/base yes table A table containing begin, end and inner parameters for an unused horizontal scroller. All are mandatory and should hold parts if a scroller (since the scroller is a composite object the game authomatically readjusts its length as necessary). Paths can be empty.
horizontal/hover yes table
horizontal/pressed yes table
vertical yes table Includes overrides for the vertical scroller. Required
vertical/base yes table See horizontal/base
vertical/hover yes table
vertical/pressed yes table

Thumbs (scrollers) and buttons can be overridden separately (i.e. you don't have to add both tables at once).

Example

"sampleScrollArea" : {
  "type": "scrollArea",
  "zlevel": 1,
  "rect": [
    100,
    40,
    200,
    80
  ],
  "children": {
    "topLabel": {
      "type" : "label",
      "position" : [50, 60],
      "value" : "Top!"
    },
    "bottomLabel": {
      "type" : "label",
      "position" : [50, 0],
      "value" : "Bottom!"
    }
  }
}

Example with buttons/thumbs override

This setting uses recolored green buttons and thumbs (like those in the list of planet bookmarks). "Children" table is empty for the sake of simplicity.

"SampleScrollArea" : {
  "type" : "scrollArea",
  "rect" : [6, 28, 123, 57],
  "buttons" : {
    "horizontal" : {
      "forward" : { "base" : "", "hover" : "", "pressed" : "" },
      "backward" : { "base" : "", "hover": "", "pressed" : "" }
    },
    "vertical" : {
      "forward" : {
        "base" : "/interface/bookmarks/scrollarea/varrow-forward.png",
        "hover" : "/interface/bookmarks/scrollarea/varrow-forwardhover.png",
        "pressed" : ""
      },
      "backward" : {
        "base" : "/interface/bookmarks/scrollarea/varrow-backward.png",
        "hover" : "/interface/bookmarks/scrollarea/varrow-backwardhover.png",
        "pressed" : ""
      }
    }
  },
  "thumbs" : {
    "horizontal" : {
      "base" : { "begin" : "", "end" : "", "inner" : "" },
      "hover" : { "begin" : "", "end" : "", "inner" : "" },
      "pressed" : { "begin" : "", "end" : "", "inner" : "" }
    },
    "vertical" : {
      "base" : {
        "begin" : "/interface/bookmarks/scrollarea/vthumb-begin.png",
        "end" : "/interface/bookmarks/scrollarea/vthumb-end.png",
        "inner" : "/interface/bookmarks/scrollarea/vthumb-inner.png"
      },
      "hover" : {
        "begin" : "/interface/bookmarks/scrollarea/vthumb-beginhover.png",
        "end" : "/interface/bookmarks/scrollarea/vthumb-endhover.png",
        "inner" : "/interface/bookmarks/scrollarea/vthumb-innerhover.png"
      },
      "pressed" : {
        "begin" : "/interface/bookmarks/scrollarea/vthumb-beginhover.png",
        "end" : "/interface/bookmarks/scrollarea/vthumb-endhover.png",
        "inner" : "/interface/bookmarks/scrollarea/vthumb-innerhover.png"
      }
    }
  },
  "children" : {}
}

LayoutWidget

We don't know much about it. Used, for example, in spaceship cockpit screen for displaying ores and weather types for the planet (icons with tooltip). Also used in the AI interface screen (the one used to access missions and crewmember info).

Think of this as a scrollArea Widget without a scrollbar.

It essentially is used to group individual widgets together. You can access children of a layout widget via 'LayoutWidgetName.childWidgetName'

This widget is particularly useful if you wish to display multiple "Screens" in one pane.


Parameter Name Mandatory Variable Type Description
type yes string Always layout. Required
layoutType possible values: "basic", "flow", "vertical".
rect yes Vec4I Layout bounding rectangle, [xmin, ymin, xmax, ymax].
position no Vec2F Array of two numbers indicating the starting position of the layout rect. This position will end up being the bottom-left corner of your layout.
size no Vec2F Array of two numbers indicating the width and height of the layout widget.
spacing no Vec2I Spacing between elements. I believe this is not used in "basic" layout types, but perhaps used in "flow" layout types.
children no JSON A JSON object containing other widgets

ItemListWidget

A widget that stores a list of items that a player can click on to select (one at any given time, like the radio button group). Often paired with a ScrollAreaWidget.

Parameter Name Mandatory Variable Type Description
type yes string Always list. Required
fillDown no boolean Determines whether new list items are inserted at the top of the list, or at the bottom. Default: true. (bottom of the list)
callback no string Name of the function called when the list's selected item changes. This includes being changed by player input, by the function widget.setListSelected(), and when nil is selected due to the current selected item being removed, such as by widget.clearListItems().
schema yes table Template for list items. The table's parameters are described below. Required

Schema parameters:

Parameter Name Mandatory Variable Type Description
selectedBG no string Background image path when selected.
unselectedBG no string Background image path when not selected.
spacing no Vec2F Distance between list items.
memberSize yes Vec2F Width and height of list items. Not required, but the item would be invisible unless a value is set.
listTemplate yes table Table of widgets. Probably not required, but necessary to differentiate list items from one another (icons, labels etc). In other words the list template is where you would configure what sub-widgets are in each listitem. You can access each sub-widget with the path: "<listName>.<itemID>.<widgetTemplateName>". You get the labelID as the return variable from the function widget.addListItem("<WidgetListName>"), and can also get the itemID from widget.getListSelected("<WidgetListName>")

Example

"sampleList" : {
  "type" : "list",
  "schema" : {
    "selectedBG" : "/interface/crafting/craftableselected2.png",
    "unselectedBG" : "/interface/crafting/craftablebackground.png",
    "spacing" : [0, 1],
    "memberSize" : [159, 20],
    "listTemplate" : {
      "background" : {
        "type" : "image",
        "file" : "/interface/crafting/craftablebackground.png",
        "position" : [2, 0],
        "zlevel" : -1
      },
      "itemName" : {
        "type" : "label",
        "position" : [25, 5],
        "hAnchor" : "left",
        "wrapWidth" : 116,
        "value" : "Replace Me"
      },
      "itemIcon" : {
        "type" : "itemslot",
        "position" : [3, 1],
        "callback" : "null"
      }
    }
  }
}

SliderWidget

A slider with "left" and "right" buttons attached.

Parameter Name Mandatory Variable Type Description
type yes string Always slider. Required
gridImage unknown string Path to background image for the grid of a slider.

ProgressBarWidget

A widget comprised of a "progress bar", in the style of a health/energy bar or a durability bar.

Parameter Name Mandatory Variable Type Description
type yes string Always progress. Required
background no string Path to background image of bar; empty bar.
progressSet yes table Contains begin, inner and end (string), which are path to an image to use for each elements of the bar (only inner is mandatory), and type (string), which can be set as repeat or stretch and will affect how the inner image will be handled.
size yes Vec2F Width and height of progress bar.
direction no string horizontal or (presumably) vertical.

Example

"sampleProgress" : {
  "zlevel" : 7,
  "type" : "progress",
  "position" : [30, -22],
  "background" : "/interface/emptybar.png",
  "size" : [60, 8],
  "progressSet" : {
    "inner" : "/interface/healthbar.png",
    "type" : "repeat"
  },
  "direction" : "horizontal"
}

SpinnerWidget

A widget comprised of two horizontal arrows facing opposite directions. Used in the base game's crafting menu and character creation menu.

Parameter Name Mandatory Variable Type Description
type yes string Always spinner. Required
upOffset no int Distance the right arrow is placed away from the left arrow. If not present the buttons will be next to each other with a small distance. To place them with 0 interval set to 8.
hAnchor no string left, mid or right. Horizontal alignment.
callback no string Name of the function called by the arrows. The left arrow calls <callback>.down, the right calls <callback>.up. In your .lua, these should be in a global table named the same as the callback.

Example

.Config file:

"sampleSpinner" : {
  "type": "spinner",
  "position" : [220, 46],
  "upOffset" : 36
}

"scriptWidgetCallbacks" : [... ,"sampleSpinner.up", "sampleSpinner.down"]

connected .lua file:

sampleSpinner = {}

    --callback function when right button is pressed
function sampleSpinner.up()
--block
end

    --called when left button is pressed
function sampleSpinner.down()
--block
end

init() {
...

NOTE:

self.sampleSpinner = {}

does NOT work.

ImageStretchWidget

This widget is used for images, where you would need to constantly stretch a pane, so that all elements fit inside of it. It may be used instead of backgrounds, when you have a scripted pane and may have random elements inside of the pane.

Parameter Name Mandatory Variable Type Description
type yes String Always imageStretch. Required
direction yes String Direction, in which the widget would stretch out. May either be "vertical", either "horizontal."
stretchSet yes Object(or dictionary) Contains 3 necessary values: "end"(usually header), "inner"(body, which is stretched out) and "begin"(usually footer). All of them are strings and lead to their corresponding images.

Widget general

Quick Navigation