WorldHandler/doc/Usercontent.md

Usercontent Reference

The World Handler provides the ability to be extended with custom tabs configured with json files.

Setup

The World Handler only loads usercontent files from ../.minecraft/config/worldhandler/usercontent/.
To add a custom GUI a new folder is required with a json file inside it named exactly the same as the folder.
That name indicates the id of the usercontent and may only consist of the characters 0-9 a-z -_:.
Additionally a javascript file can be created inside the folder with exactly the same name as the folder.

Example setup for a custom GUI with id example:

../.minecraft/config/worldhandler/usercontent/example/example.json
../.minecraft/config/worldhandler/usercontent/example/example.js

An example GUI can be found here

Index

Content: A single GUI of the World Handler i.e. the main page
Category: A collection of contents that are grouped together and are displayed in tabs next to each other
Elements: A structure of buttons simplifying the creation of larger menus

General Structure

{
	"model": {
		"commands": [
			#See commands
		]
	},
	"gui": {
		"title": "", #The title of the gui
		"tab": {
			"title": "", #The title of the tab
			"category": "", #The category where the tab should be clickable in (See reference/category-ids)
			"category_index": 0, #The index of the tab (left: 0, right: last tab index)
			"active_content": "" #The id of the active content (See reference/content-ids)
		},
		"buttons": [
			#See buttons
		],
		"elements": [
			#See elements
		],
		"texts": [
			#See texts
		]
	}
}

Commands

All commands that should be modifiable, executable or visible by the command syntax need to be modeled

{
	"name": "", #The root of the command
	"syntax": [
		{
			"name": "", #Placeholder text for the argument
			"type": "", #Type of the argument (See table below for available types)
			"required": true #Whethter or not this argument is required in order to complete the command
		}
	],
	"visible": {
		#See widget-states
	}
}

Argument types	Comment
byte	Default java byte
short	Default java short
int	Default java integer
float	Default java float
double	Default java double
long	Default java long
boolean	Default java boolean
string	Default java string
greedy_string	String that can be read across whitespaces. (usually in quotes)
resource_location	Minecraft resource location. Example: namespace:resource
item_resource_location	Resource location with attached nbt. Example: namespace:resource{"nbt":"example"}
block_resource_location	Item resource location with attached block tag. Example: namespace:resource[state=example]
nbt	Minecraft data structure. Example: {"nbt":"example"}
coordinate_int	An integer that can either be absolute or relative in a global (prefix: ~) or local (prefix: ^) context
coordinate_double	A double that can either be absolute or relative in a global (prefix: ~) or local (prefix: ^) context
target_selector	Filter for entities. This implementation only supports @e with arguments. Example: @e[type=player]
player	Username of the player that will be automatically set by the system

Buttons

{
	"text": "", #Optional
	"type": "", #See table below for available types
	"dimensions": {
		"x": 0,
		"y": 0,
		"width": 114,
		"height": 20
	},
	"action": {
		#See action
	},
	"attributes": {
		"id": "",
		"item": "", #Resource location
		"icon": "", #See reference/icon-ids for available ids
		"visible": {
			#See widget-states
		},
		"enabled": {
			#See widget-states
		}
	}
}

Button type	Description	Actions	Required attributes	Optional Attributes
button	Simple button	open, set, run, back, back_to_game, js	-	tooltip
textfield	Simple textfield	set, js	id	-
item_button	Button with an item instead of text	open, set, run, back, back_to_game, js	item	-
icon_button	Button with an icon instead of text	open, set, run, back, back_to_game, js	icon	tooltip
list_button	Button with the option to cycle through items	set, js	items	-
slider	Simple slider	set, js	id, min, max	start

Elements

"type": "", #See table below for available types
"dimensions": {
	"x": 0,
	"y": 0,
	"width": 114,
	"height": 20
},
"attributes": {
	"id": "",
	"length": 1,
	"items": [
		{
			"id": "",
			"translation": "" #Translation key or string value
		}
	]
}

Element type	Description	Required attributes	Optional Attributes
page_list	Creates column of buttons with length options to choose from and two buttons for navigating left and right	id, length, items	-

Text

{
	"text": "",
	"x": 0,
	"y": 0,
	"color": 2039583 #Color of the text (red << 16 + green << 8 + blue)
}

Action

"action": {
	"type": "", #See table below for available types
	"attributes": {
		"function": "", #Name of the js function
		"command": 0, #Index of the command inside the json file
		"index": 0, #Argument index
		"value": ""
	}
}

Action type	Description	Required attributes	Optional Attributes
open	Opens the content associated with value	value	-
set	Sets the argument index of command command to value or the value provided by the system	index, command	value
run	Runs the command from value	value	-
back	Goes back to the previous content	-	-
back_to_game	Closes the GUI	-	-
js	Invokes the javascript function function (with argument value)	function	value

Widget states

There are two widget states: visible and enabled
This structure is optional.

"visible": {
	"type": "",
	"bool": true
	"function": "" #Name of the js function
}

State type	Description	Required attributes	Optional Attributes
bool	The state will be determined by the value of the bool attribute	bool	-
js	Invokes the javascript function function and uses the result	function	-

JavaScript API

The JavaScript interpreter comes with an instance of UsercontentAPI available for reference with api

Example: api.addChatMessage("Hello World")

Function	Description
String getValue(String id)	returns the value stored by a button or element with id id
String getCommandArgument(int command, int index)	returns the argument at index index of command command
void setCommandArgument(int command, int index, String object)	sets the argument at index index of command command to object
void addChatMessage(Object object)	prints the object to the ingame chat

ActionHelper

Example:

var ActionHelper = Java.type('exopandora.worldhandler.helper.ActionHelper');
ActionHelper.displayGui();

Function	Description
void backToGame()	Closes the GUI
void back(String id)	Tries to open the back content of content with id id
void open(String id)	Tries to open the content with id id
void timeDawn()	Sets the time to dawn
void timeNoon()	Sets the time to noon
void timeSunset()	Sets the time to sunset
void timeMidnight()	Sets the time to midnight
void weatherClear()	Sets the weather to clear
void weatherRain()	Sets the weather to rain
void weatherThunder()	Sets the weather to thunder
void difficultyPeaceful()	Sets the difficulty to peaceful
void difficultyEasy()	Sets the difficulty to easy
void difficultyNormal()	Sets the difficulty to normal
void difficultyHard()	Sets the difficulty to hard
void gamemodeSurvival()	Sets the gamemode to survival
void gamemodeCreative()	Sets the gamemode to creative
void gamemodeAdventure()	Sets the gamemode to adventure
void gamemodeSpectator()	Sets the gamemode to spectator
void displayGui()	Tries to open the World Handler GUI (same as pressing the activation button)

Reference

Content ids	Category ids	Icon ids
main	main	weather_sun
containers	entities	weather_rain
multiplayer	items	weather_storm
summon	blocks	difficulty_peaceful
custom_item	world	difficulty_easy
enchantment	player	difficulty_normal
edit_blocks	scoreboard	difficulty_hard
sign_editor		time_dawn
note_editor		time_noon
world		time_sunset
gamerules		time_midnight
recipes		gamemode_survival
player		gamemode_creative
experience		gamemode_adventure
advancements		gamemode_spectator
scoreboard_objectives		butcher
scoreboard_teams		potion
scoreboard_players		achievements
change_world		home
continue		settings
potions		reload
butcher
butcher_settings
settings